T3 Env stops the build with Invalid environment variables
❌ 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.
Fix it fast
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)))"2Match what you see, then jump to its fix
- 1
The 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
A 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
Type 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
The error appears in docker build, while npm run dev works on your machineA Docker or CI build runs without the runtime variablesFix
- 1
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/null2Fix
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 buildConfirmed by nextjs.org
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/null2Fix
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 devConfirmed by env.t3.gg
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/null2Fix
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 buildConfirmed by env.t3.gg
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 " Dockerfile2Fix
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=13Verify
Build the image, then run the container with the real values.
docker build -t my-app . && docker run --env-file .env my-appConfirmed by env.t3.gg
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
A Next.js environment variable is undefined in the browser or after deploy
TypeError: Cannot read properties of undefined
Next.js only gives the browser variables whose names start with NEXT_PUBLIC_, and it copies their values into the JavaScript at build time.
4 causes, each with a fixWeb 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 fix