agent-skills/skills/turborepo/references/caching/gotchas.md

Debugging Cache Issues

Diagnostic Tools

--summarize

Generates a JSON file with all hash inputs. Compare two runs to find differences.

turbo build --summarize
# Creates .turbo/runs/<run-id>.json

The summary includes:

• Global hash and its inputs
• Per-task hashes and their inputs
• Environment variables that affected the hash

Comparing runs:

# Run twice, compare the summaries
diff .turbo/runs/<first-run>.json .turbo/runs/<second-run>.json

--dry / --dry=json

See what would run without executing anything:

turbo build --dry
turbo build --dry=json  # machine-readable output

Shows cache status for each task without running them.

--force

Skip reading cache, re-execute all tasks:

turbo build --force

Useful to verify tasks actually work (not just cached results).

Unexpected Cache Misses

Symptom: Task runs when you expected a cache hit.

Environment Variable Changed

Check if an env var in the env key changed:

{
  "tasks": {
    "build": {
      "env": ["API_URL", "NODE_ENV"]
    }
  }
}

Different API_URL between runs = cache miss.

.env File Changed

.env files aren't tracked by default. Add to inputs:

{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local"]
    }
  }
}

Or use globalDependencies for repo-wide env files:

{
  "globalDependencies": [".env"]
}

Lockfile Changed

Installing/updating packages changes the global hash.

Source Files Changed

Any file in the package (or in inputs) triggers a miss.

turbo.json Changed

Config changes invalidate the global hash.

Incorrect Cache Hits

Symptom: Cached output is stale/wrong.

Missing Environment Variable

Task uses an env var not listed in env:

// build.js
const apiUrl = process.env.API_URL;  // not tracked!

Fix: add to task config:

{
  "tasks": {
    "build": {
      "env": ["API_URL"]
    }
  }
}

Missing File in Inputs

Task reads a file outside default inputs:

{
  "tasks": {
    "build": {
      "inputs": [
        "$TURBO_DEFAULT$",
        "../../shared-config.json"  // file outside package
      ]
    }
  }
}

Useful Flags

# Only show output for cache misses
turbo build --output-logs=new-only

# Show output for everything (debugging)
turbo build --output-logs=full

# See why tasks are running
turbo build --verbosity=2

Quick Checklist

Cache miss when expected hit:

1. Run with --summarize, compare with previous run
2. Check env vars with --dry=json
3. Look for lockfile/config changes in git

Cache hit when expected miss:

1. Verify env var is in env array
2. Verify file is in inputs array
3. Check if file is outside package directory