Maaz Zindani

Loading the index…

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

T3 Env stops the build with Invalid environment variables

Error❌ Invalid environment variables:

Short answer

T3 Env validates process.env against your Zod schema when the app starts or builds, and stops on the first failure. The printed issues name each bad key. Usually a variable is missing from the .env file or the build environment, is empty, or lacks the NEXT_PUBLIC_ prefix on the client side.

  • Applies to t3-env, Next.js 15, Zod 4, Node.js 22, Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the issues printed under the first line. Each one has a path (the variable name) and a message. Then check what the process really sees for that name.

    node -e "console.log(Object.keys(process.env).filter(k => /DATABASE|NEXT_PUBLIC/.test(k)))"
  2. 2Match what you see, then jump to its fix

    1. 1The issue path names a server variable, and the message says it is required or undefinedThe variable is missing or sits in the wrong .env fileFix
    2. 2A line such as PORT= or SMTP_PASS= in .env, and the issue says a string is too short or a number is invalidThe value is an empty stringFix
    3. 3Type error or runtime issue on a key in the client schema; the value is undefined in the browserA client variable is not prefixed, or is not listed in runtimeEnvFix
    4. 4The error appears in docker build, while npm run dev works on your machineA Docker or CI build runs without the runtime variablesFix

What does the error look like?

  • ❌ Invalid environment variables:
  • Error: Invalid environment variables

Cause 1 of 4

The variable is missing or sits in the wrong .env file

1Check

Next.js loads .env files from the project root. With a src folder they must stay in the root, not inside src. In a test run .env.local is skipped.

ls -a | grep "^\.env"
grep -n "DATABASE_URL" .env .env.local 2>/dev/null

2Fix

Put the variable in .env or .env.local at the project root, or export it in the shell that runs the command, then start again.

# .env.local (project root)
DATABASE_URL="postgresql://user:pass@localhost:5432/app"

3Verify

Run the dev server or the build again.

npm run build

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

The value is an empty string

1Check

By default T3 Env hands the raw values to Zod, so an empty string stays an empty string and fails min(1) or number checks.

grep -n "=$" .env .env.local 2>/dev/null

2Fix

Fill in the value, or set emptyStringAsUndefined to true so empty strings count as missing and defaults can apply.

export const env = createEnv({
  server: { PORT: z.coerce.number().default(3000) },
  runtimeEnv: process.env,
  emptyStringAsUndefined: true,
})

3Verify

Start the app; the issue list should no longer include that key.

npm run dev

Confirmed by env.t3.gg

Did this fix it?

Cause 3 of 4

A client variable is not prefixed, or is not listed in runtimeEnv

1Check

The clientPrefix is enforced at type level and at runtime. In the Next.js setup, runtimeEnv is strict, so you list every key by hand, because Next.js only bundles variables that are explicitly accessed.

grep -n "runtimeEnv" -A12 src/env.* env.* 2>/dev/null

2Fix

Name the client variable with the NEXT_PUBLIC_ prefix and add it to runtimeEnv as process.env.NEXT_PUBLIC_NAME.

client: {
  NEXT_PUBLIC_API_URL: z.string().url(),
},
runtimeEnv: {
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
},

3Verify

Rebuild, because NEXT_PUBLIC_ values are inlined at build time.

npm run build

Confirmed by env.t3.gg

Did this fix it?

Cause 4 of 4

A Docker or CI build runs without the runtime variables

1Check

The docs describe skipValidation for Docker builds where not all variables are present when the image is built.

grep -n "ENV \|ARG " Dockerfile

2Fix

Turn validation off for the build step only, with a flag you set yourself in the Dockerfile.

// env.ts
export const env = createEnv({
  // ...
  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
})

# Dockerfile (build stage)
ENV SKIP_ENV_VALIDATION=1

3Verify

Build the image, then run the container with the real values.

docker build -t my-app . && docker run --env-file .env my-app

Confirmed by env.t3.gg

Did this fix it?

How do I stop it coming back?

  • Keep a .env.example listing every key in the schema.
  • Import the env file in next.config so a missing value fails the build, not a request.
  • Treat skipValidation as a build-only switch; the running app should validate.

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.