1# Environment Variable Gotchas
2 
3Common mistakes and how to fix them.
4 
5## .env Files Must Be in `inputs`
6 
7Turbo does NOT read `.env` files. Your framework (Next.js, Vite, etc.) or `dotenv` loads them. But Turbo needs to know when they change.
8 
9**Wrong:**
10 
11```json
12{
13  "tasks": {
14    "build": {
15      "env": ["DATABASE_URL"]
16    }
17  }
18}
19```
20 
21**Right:**
22 
23```json
24{
25  "tasks": {
26    "build": {
27      "env": ["DATABASE_URL"],
28      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local", ".env.production"]
29    }
30  }
31}
32```
33 
34## Strict Mode Filters CI Variables
35 
36In strict mode, CI provider variables (GITHUB_TOKEN, GITLAB_CI, etc.) are filtered unless explicitly listed.
37 
38**Symptom:** Task fails with "authentication required" or "permission denied" in CI.
39 
40**Solution:**
41 
42```json
43{
44  "globalPassThroughEnv": ["GITHUB_TOKEN", "GITLAB_CI", "CI"]
45}
46```
47 
48## passThroughEnv Doesn't Affect Hash
49 
50Variables in `passThroughEnv` are available at runtime but changes WON'T trigger rebuilds.
51 
52**Dangerous example:**
53 
54```json
55{
56  "tasks": {
57    "build": {
58      "passThroughEnv": ["API_URL"]
59    }
60  }
61}
62```
63 
64If `API_URL` changes from staging to production, Turbo may serve a cached build pointing to the wrong API.
65 
66**Use passThroughEnv only for:**
67 
68- Auth tokens that don't affect output (SENTRY_AUTH_TOKEN)
69- CI metadata (GITHUB_RUN_ID)
70- Variables consumed after build (deploy credentials)
71 
72## Runtime-Created Variables Are Invisible
73 
74Turbo captures env vars at startup. Variables created during execution aren't seen.
75 
76**Won't work:**
77 
78```bash
79# In package.json scripts
80"build": "export API_URL=$COMPUTED_VALUE && next build"
81```
82 
83**Solution:** Set vars before invoking turbo:
84 
85```bash
86API_URL=$COMPUTED_VALUE turbo run build
87```
88 
89## Different .env Files for Different Environments
90 
91If you use `.env.development` and `.env.production`, both should be in inputs.
92 
93```json
94{
95  "tasks": {
96    "build": {
97      "inputs": [
98        "$TURBO_DEFAULT$",
99        ".env",
100        ".env.local",
101        ".env.development",
102        ".env.development.local",
103        ".env.production",
104        ".env.production.local"
105      ]
106    }
107  }
108}
109```
110 
111## Complete Next.js Example
112 
113```json
114{
115  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
116  "globalEnv": ["CI", "NODE_ENV", "VERCEL"],
117  "globalPassThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
118  "tasks": {
119    "build": {
120      "dependsOn": ["^build"],
121      "env": ["DATABASE_URL", "NEXT_PUBLIC_*", "!NEXT_PUBLIC_ANALYTICS_ID"],
122      "passThroughEnv": ["SENTRY_AUTH_TOKEN"],
123      "inputs": [
124        "$TURBO_DEFAULT$",
125        ".env",
126        ".env.local",
127        ".env.production",
128        ".env.production.local"
129      ],
130      "outputs": [".next/**", "!.next/cache/**"]
131    }
132  }
133}
134```
135 
136This config:
137 
138- Hashes DATABASE*URL and NEXT_PUBLIC*\* vars (except analytics)
139- Passes through SENTRY_AUTH_TOKEN without hashing
140- Includes all .env file variants in the hash
141- Makes CI tokens available globally
142 
143### With `futureFlags.globalConfiguration`
144 
145The same config using the `global` key. The `.env` files move to `global.inputs`, which means they get folded into each task's hash individually rather than the global hash. This lets tasks exclude specific `.env` files if needed.
146 
147```json
148{
149  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
150  "futureFlags": { "globalConfiguration": true },
151  "global": {
152    "env": ["CI", "NODE_ENV", "VERCEL"],
153    "passThroughEnv": ["GITHUB_TOKEN", "VERCEL_URL"],
154    "inputs": [".env", ".env.local", ".env.production", ".env.production.local"]
155  },
156  "tasks": {
157    "build": {
158      "dependsOn": ["^build"],
159      "env": ["DATABASE_URL", "NEXT_PUBLIC_*", "!NEXT_PUBLIC_ANALYTICS_ID"],
160      "passThroughEnv": ["SENTRY_AUTH_TOKEN"],
161      "outputs": [".next/**", "!.next/cache/**"]
162    }
163  }
164}
165```
166 
167With this approach, a task that doesn't care about `.env.production` can exclude it:
168 
169```json
170"lint": {
171  "inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/.env.production"]
172}
173```
174 
175This wouldn't have been possible with `globalDependencies`, where `.env.production` would be baked into the global hash and affect every task unconditionally.
176