turborepo 2.x remote cache misses on every ci run but hits locally Turborepo

Two identical runs producing different global hashes means an environment variable is in the hash and its value changes per run. That is basically the only thing it can be.

Dump the inputs and read them:

turbo run build --dry=json > dry.json
jq '.globalCacheInputs' dry.json

That gives you the env vars, the lockfile hash, the root package.json hash and the global dependencies. Diff that file between two CI runs. Ninety percent of the time the culprit is one of GITHUB_RUN_ID, GITHUB_SHA, a build number, or a release identifier like SENTRY_RELEASE that you added to globalEnv months ago and forgot about.

The fix is to move anything volatile out of globalEnv and into globalPassThroughEnv. Pass-through variables are handed to the task at runtime but are deliberately excluded from the hash, which is exactly what you want for a release tag - the build output does not meaningfully depend on it, and if it does, that is a different conversation.

Also check whether you have "globalEnv": ["*"] anywhere, because that is a foot-gun that puts the entire CI environment in the hash and guarantees a permanent miss.

Since you already found the env var, some other things in the same family that bite people, so this thread is useful later:

• Files present locally but not on CI. Task inputs default to everything tracked in the package directory. If you have a .env.local or a generated file that exists on your machine and not on CI, the hashes differ in the opposite direction and you get misses only locally.
• Cache disabled silently. If TURBO_TOKEN is wrong rather than missing, some setups log a warning that scrolls past and then run uncached. Grep the log for the word cache before trusting that it is enabled.
• Different --filter between local and CI. Filtering changes the task graph, and a task that runs with different dependencies has a different hash.
• Lockfile churn. Any package manager that rewrites the lockfile during install invalidates the global hash on every run. Frozen lockfile in CI, always.

One more that is easy to miss: package manager version drift. If your machine runs pnpm 10.4 and CI runs 10.1 and the lockfile format or resolution differs even slightly, the lockfile hash changes and everything downstream misses.

Pin it in the root package.json with "packageManager": "[email protected]" and let corepack enforce it. Costs nothing, removes an entire category of "works on my machine" from the build cache specifically.

For next time - turbo run build --verbosity=2 prints the hash for each task as it computes it, so you can see which task diverges first. If the global hash is stable and only one package misses, the answer is in that package's inputs rather than the environment.

Remote cache only actually works if you are running on Vercel's own CI runners. Elsewhere it uploads but the read path is restricted, which is why you see artifacts going up and nothing coming down. It is a platform lock-in thing.

Every build cache problem is one of: something in the hash that should not be, or something not in the hash that should be. The second one is worse because it ships.