Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Turborepo says an environment variable is not listed in turbo.json

Error$VARIABLE is not listed as a dependency in turbo.json

Short 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.

  • Applies to Turborepo 2, Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --summarize
  2. 2Match what you see, then jump to its fix

    1. 1ESLint 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. 2The 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. 3Changing .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. 4turbo/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

What does the error look like?

  • $VARIABLE is not listed as a dependency in turbo.json
  • A variable is undefined in the build only when it runs through turbo
  • turbo/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.json

2Fix

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 lint

Confirmed by turborepo.dev

Did this fix it?

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 --summarize

2Fix

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 build

Confirmed by turborepo.dev

Did this fix it?

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 build

Confirmed by turborepo.dev

Did this fix it?

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.