Turborepo says an environment variable is not listed in turbo.json
$VARIABLE is not listed as a dependency in turbo.jsonShort answer
Turborepo only passes variables to a task, and only hashes them, when turbo.json names them. In strict mode, the default, an unlisted variable is filtered out of the task. Add it to env or globalEnv if it changes the output, or to passThroughEnv if it only has to exist at runtime.
Fix it fast
1Find out which cause you have
Run the build with a run summary and look at the env and globalEnv keys in the task entry. It shows which variables Turborepo hashed and which are missing.
npx turbo run build --summarize2Match what you see, then jump to its fix
- 1
ESLint reports the variable, or the build is restored from cache after you changed its valueThe variable changes the build output but is not declaredFix - 2
The variable is undefined inside the task in strict mode, and it should not change the cache keyThe task needs the variable only at runtime, for example a CI or platform variableFix - 3
Changing .env does not rebuild the app, or the value is missing under turboThe value lives in a .env file that Turborepo does not hashFix - 4
turbo/no-undeclared-env-vars reports variables you want to leave out of the hash on purposeA lint rule is flagging names that are not real build inputsFix
- 1
What does the error look like?
$VARIABLE is not listed as a dependency in turbo.jsonA variable is undefined in the build only when it runs through turboturbo/no-undeclared-env-vars ESLint error
Cause 1 of 4
The variable changes the build output but is not declared
1Check
Find where the code reads the variable, then check whether turbo.json lists it under the task's env or under globalEnv.
grep -rn "MY_API_URL" apps packages --include=*.ts --include=*.tsx
cat turbo.json2Fix
Declare it. Use env for one task, or globalEnv if every task depends on it.
{
"globalEnv": ["IMPORTANT_GLOBAL_VARIABLE"],
"tasks": {
"build": {
"env": ["MY_API_URL", "MY_API_KEY"]
}
}
}3Verify
Run the build again, then run the ESLint check for the package.
npx turbo run build
npx turbo run lintConfirmed by turborepo.dev
Cause 2 of 4
The task needs the variable only at runtime, for example a CI or platform variable
1Check
Strict mode filters out every variable that is not declared, including variables set by your CI vendor. Check whether the value is needed to run the task but would not change its output.
npx turbo run build --summarize2Fix
Declare it as a pass-through variable. It reaches the task but is left out of the hash.
{
"globalPassThroughEnv": ["CI_RUNNER_TOKEN"],
"tasks": {
"build": {
"passThroughEnv": ["DEPLOY_TOKEN"]
}
}
}3Verify
Run the task and confirm the variable is present when it runs.
npx turbo run buildConfirmed by turborepo.dev
Cause 3 of 4
The value lives in a .env file that Turborepo does not hash
1Check
Turborepo does not load .env files into the task. Your framework or a tool such as dotenv loads them, and Turborepo hashes them only if they are listed in inputs. Keeping the file inside each app package, not the repository root, is the documented advice.
ls -a apps/web | grep '^.env'2Fix
List the file in the task inputs, and keep the variables it defines declared in env.
{
"tasks": {
"build": {
"inputs": ["$TURBO_DEFAULT$", ".env*"],
"env": ["MY_API_URL"]
}
}
}3Verify
Change a value in the .env file and confirm the next run is a cache miss.
npx turbo run buildConfirmed by turborepo.dev
Cause 4 of 4
A lint rule is flagging names that are not real build inputs
1Check
The rule from eslint-config-turbo reports every variable the code reads that turbo.json does not declare.
npx eslint .2Fix
Declare the variable if it matters. If it should stay out of the hash, add its name pattern to the rule's allowList.
import turboConfig from "eslint-config-turbo/flat";
export default [
...turboConfig,
{
rules: {
"turbo/no-undeclared-env-vars": [
"error",
{ allowList: ["^ENV_[A-Z]+$"] },
],
},
},
];3Verify
Run ESLint again and confirm only the variables you wanted flagged remain.
npx eslint .Confirmed by turborepo.dev
How do I stop it coming back?
- Declare a variable in turbo.json in the same pull request that starts reading it.
- Keep the ESLint rule on in CI so an undeclared variable fails the review, not the deploy.
- Use env for values that change output and passThroughEnv for secrets that only have to exist.
- Use the loose env mode only while migrating, since it can restore a cache entry built with a different value.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix