Your New Gemini API Key Never Took Effect, and Load Order Wasn't the Reason

dotenv Parses the File Without Injecting It

One more behavior stretched the debugging session: dotenv parses the file correctly while not injecting anything into the environment.

I confirmed it on the Node side, with dotenv 17.4.2 and an old key already in the shell.

import dotenv from "dotenv";
 
const before = process.env.GEMINI_API_KEY;          // the old key, from the shell
const r1 = dotenv.config({ path: "/tmp/keyaudit/.env" });
const after = process.env.GEMINI_API_KEY;
const r2 = dotenv.config({ path: "/tmp/keyaudit/.env", override: true });
 
console.log(JSON.stringify({
  before,
  after_default: after,
  after_override_true: process.env.GEMINI_API_KEY,
  parsed_seen: r1.parsed?.GEMINI_API_KEY,          // <- the trap
}, null, 2));

The output:

◇ injected env (0) from .env // tip: ⌘ override existing { override: true }
{
  "before": "OLD_STANDARD_KEY_from_shell",
  "after_default": "OLD_STANDARD_KEY_from_shell",
  "after_override_true": "NEW_AUTH_KEY_from_dotenv",
  "parsed_seen": "NEW_AUTH_KEY_from_dotenv"
}

Look at parsed_seen. The parsed property on the return value holds the new key. The file was read, and the value was parsed correctly. process.env is still the old one.

Mid-debug, when you want to check whether .env is really being read, printing result.parsed shows you the new value. Read that as "it works" and the actual problem, that nothing was injected, drops out of view. That cost me the better part of an hour.

The single honest signal is the injected env (0) line, which is easy to lose among other output. Python behaves the same way: the value did not change across load_dotenv().

Nothing raises. Status codes stay at 200. This shape, where an assumption quietly stops holding, mirrors the way the deprecated temperature and top_p parameters are accepted and then ignored. A change that stops your job is easier to live with than one that does not.

Put the Overwrite Policy in One Place

With the cause identified, the fix was to make "which path may overwrite" an explicit, single decision. Leaving implicit overrides scattered across the codebase means the next migration stalls in the same spot.

The approach:

1. Route every supply through one function instead of a direct os.environ[...] = ...
2. Keep the set of paths allowed to overwrite inside that function
3. Record, at that moment, whether the supply was actually applied

The third point carries the weight. "I handed over the new key" and "the new key was adopted" are different facts. This whole failure began with me treating them as one.

Record Both Supply and Read in a Ledger

Here is the audit shim I ended up with. It does not replace os.environ itself; replacing it drags in library behavior I do not fully control. It only pulls supply and read through my own functions.

"""Record where a key came from, at the moment it is read."""
import os, json
 
class KeyLedger:
    def __init__(self):
        self.writes = []
        self.reads = []
 
    def supply(self, name, value, source):
        prev = os.environ.get(name)
        # apply when nothing is there; otherwise ask whether this source may overwrite
        applied = value is not None and (prev is None or self.policy(source))
        self.writes.append({
            "name": name, "source": source,
            "had_previous": prev is not None,
            "applied": bool(applied),
            "fingerprint": self.fp(value),
        })
        if applied:
            os.environ[name] = value
        return applied
 
    def policy(self, source):
        # the single place where overwrite permission is granted
        return source in {"secret-manager", "explicit-cli-flag"}
 
    def read(self, name):
        v = os.environ.get(name)
        owner = next((w["source"] for w in reversed(self.writes)
                      if w["name"] == name and w["applied"]), "pre-existing-process-env")
        self.reads.append({"name": name, "resolved_from": owner, "fingerprint": self.fp(v)})
        return v
 
    @staticmethod
    def fp(v):
        # never keep the value; first four chars, last four chars, and length
        if v is None:
            return None
        return f"{v[:4]}…{v[-4:]}(len={len(v)})"
 
    def report(self):
        return json.dumps({"writes": self.writes, "reads": self.reads},
                          ensure_ascii=False, indent=2)

Run under the assumption that CI already exported the old key:

{
  "writes": [
    {
      "name": "GEMINI_API_KEY",
      "source": "dotenv-file",
      "had_previous": true,
      "applied": false,
      "fingerprint": "NEW_…tenv(len=24)"
    },
    {
      "name": "GEMINI_API_KEY",
      "source": "secret-manager",
      "had_previous": true,
      "applied": true,
      "fingerprint": "NEW_…ager(len=32)"
    }
  ],
  "reads": [
    {
      "name": "GEMINI_API_KEY",
      "resolved_from": "secret-manager",
      "fingerprint": "NEW_…ager(len=32)"
    }
  ]
}

That applied: false line is the entire piece of information I was missing. "A path supplied the new key and was not adopted" now fits on one row.

The fingerprint keeps only a fingerprint by design. Writing key values into this ledger would turn the ledger itself into a new leak path. First four characters, last four, and length were enough to tell old from new. The length difference of 24 versus 32 also makes visual triage quick.

Keeping resolved_from means that during an incident, the supply source you need to fix reads straight off the record. My sense is that this single line is the difference between a short investigation and a long one.

Order the Migration by Supply Source, Not by Code

After the ledger was in, I rebuilt the migration order. It used to be "fix the code, run it, ship if it passes," which pushes the supply-side inventory to the very end.

Now it goes:

1. List every place that supplies GEMINI_API_KEY, working from runtime configuration rather than code search
2. Decide on exactly one path that is allowed to overwrite
3. Put the new key into that one path
4. Confirm the ledger reports applied: true
5. Only then remove the old key from the remaining paths

Step 5 belongs last. Delete the old key first and you lose your only way to learn which path was actually in effect. Since adopting the rule of seeing applied: true with my own eyes before deleting anything, half-migrated cutovers have stopped happening.

The same pattern shows up in model ID swaps. I wrote about the version where tests stay green while production alone goes down in how recorded fixtures hide a model retirement, and the freshness gate that catches it. Both are the same problem viewed from different sides: an old value quietly surviving.

Two September Deadlines of Different Kinds

This month holds two deadlines with genuinely different characters.

The first is a model ID replacement, so a string search across the repository catches every instance. The work is easy to plan and easy to declare finished. I covered the deadline itself in taking inventory of what depends on the September 30 removal.

The second is the subject of this article. Because the values live outside the code, no search will tell you that you are done. The only way to judge is to look at what actually reached the running process. Running several scheduled jobs on my own, I now start with whichever deadline offers the fewest ways to verify completion, rather than whichever has the fewest days left.

When to pin a referenced model or key, and when to let it move, sits on the same ground as the day I stopped tracking gemini-flash-latest.

One Step to Take With You

Write down, today, every place in your project that supplies GEMINI_API_KEY. Not the places that read it, the places that put a value there. If you find three or more, check how many of them are allowed to overwrite. If the answer is two or more, a key swap that silently does nothing can happen to you at any time.

I spent real time on the wrong hypothesis about load order before getting here. If this spares even one person the same detour, the writing was worth it.