1# Debugging Cache Issues
2 
3## Diagnostic Tools
4 
5### `--summarize`
6 
7Generates a JSON file with all hash inputs. Compare two runs to find differences.
8 
9```bash
10turbo build --summarize
11# Creates .turbo/runs/<run-id>.json
12```
13 
14The summary includes:
15 
16- Global hash and its inputs
17- Per-task hashes and their inputs
18- Environment variables that affected the hash
19 
20**Comparing runs:**
21 
22```bash
23# Run twice, compare the summaries
24diff .turbo/runs/<first-run>.json .turbo/runs/<second-run>.json
25```
26 
27### `--dry` / `--dry=json`
28 
29See what would run without executing anything:
30 
31```bash
32turbo build --dry
33turbo build --dry=json  # machine-readable output
34```
35 
36Shows cache status for each task without running them.
37 
38### `--force`
39 
40Skip reading cache, re-execute all tasks:
41 
42```bash
43turbo build --force
44```
45 
46Useful to verify tasks actually work (not just cached results).
47 
48## Unexpected Cache Misses
49 
50**Symptom:** Task runs when you expected a cache hit.
51 
52### Environment Variable Changed
53 
54Check if an env var in the `env` key changed:
55 
56```json
57{
58  "tasks": {
59    "build": {
60      "env": ["API_URL", "NODE_ENV"]
61    }
62  }
63}
64```
65 
66Different `API_URL` between runs = cache miss.
67 
68### .env File Changed
69 
70`.env` files aren't tracked by default. Add to `inputs`:
71 
72```json
73{
74  "tasks": {
75    "build": {
76      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local"]
77    }
78  }
79}
80```
81 
82Or use `globalDependencies` for repo-wide env files:
83 
84```json
85{
86  "globalDependencies": [".env"]
87}
88```
89 
90With `futureFlags.globalConfiguration`, use `global.inputs` instead. The key difference: `global.inputs` files are folded into each task's hash individually (not the global hash), so tasks can exclude specific files with negation globs.
91 
92```json
93{
94  "futureFlags": { "globalConfiguration": true },
95  "global": {
96    "inputs": [".env"]
97  }
98}
99```
100 
101### Lockfile Changed
102 
103Installing/updating packages changes the global hash.
104 
105### Source Files Changed
106 
107Any file in the package (or in `inputs`) triggers a miss.
108 
109### turbo.json Changed
110 
111Config changes invalidate the global hash.
112 
113## Incorrect Cache Hits
114 
115**Symptom:** Cached output is stale/wrong.
116 
117### Missing Environment Variable
118 
119Task uses an env var not listed in `env`:
120 
121```javascript
122// build.js
123const apiUrl = process.env.API_URL; // not tracked!
124```
125 
126Fix: add to task config:
127 
128```json
129{
130  "tasks": {
131    "build": {
132      "env": ["API_URL"]
133    }
134  }
135}
136```
137 
138### Missing File in Inputs
139 
140Task reads a file outside default inputs:
141 
142```json
143{
144  "tasks": {
145    "build": {
146      "inputs": [
147        "$TURBO_DEFAULT$",
148        "../../shared-config.json" // file outside package
149      ]
150    }
151  }
152}
153```
154 
155## Useful Flags
156 
157```bash
158# Only show output for cache misses
159turbo build --output-logs=new-only
160 
161# Show output for everything (debugging)
162turbo build --output-logs=full
163 
164# See why tasks are running
165turbo build --verbosity=2
166```
167 
168## Debugging with `globalConfiguration` Enabled
169 
170When `futureFlags.globalConfiguration` is on, `global.inputs` files appear in per-task hash inputs (not the global hash). If you're getting unexpected cache misses:
171 
1721. Check `--summarize` output — global input files will show up in the **task inputs** section, not the global hash section
1732. Verify tasks aren't accidentally excluding global inputs via negation globs in `inputs`
1743. Remember that toggling the `globalConfiguration` flag itself invalidates all caches (the flag value is part of the global hash)
175 
176If you're getting unexpected cache **hits** after changing a global input file, the task may be excluding that file with a negation glob. Check the task's `inputs` for `!$TURBO_ROOT$/...` patterns.
177 
178## Quick Checklist
179 
180Cache miss when expected hit:
181 
1821. Run with `--summarize`, compare with previous run
1832. Check env vars with `--dry=json`
1843. Look for lockfile/config changes in git
185 
186Cache hit when expected miss:
187 
1881. Verify env var is in `env` array
1892. Verify file is in `inputs` array
1903. Check if file is outside package directory
191