Fixing Environment Variable Issues in Next.js After Dockerizing Your App

If you use Next.js without Vercel, you have probably faced environment variable issues after dockerizing your application.

I spent a lot of time debugging this problem. Even after reading the Next.js environment variables documentation several times, things still did not work correctly.

So here is the setup that finally worked for me.

My stack:

• Next.js 16.1.6
• Node.js 24.12.0
• OS: Windows 11

Understanding the Difference Between Public and Private Variables

The most important thing is to separate public and private environment variables correctly.

Public Environment Variables

Public variables are values that can safely be exposed to the client side, such as an API URL.

Create them inside a .env file using the NEXT_PUBLIC_ prefix.

Example:

NEXT_PUBLIC_API_URL=https://api.example.com

Important

You do not need to add this .env file inside your docker-compose.yaml.

Instead, copy it directly in your Docker image through the Dockerfile:

COPY .env .env
#OR
COPY .env ./

This allows Next.js to access public variables during the build process.

After that, you can use the variable anywhere on the client side:

process.env.NEXT_PUBLIC_API_URL

Private Environment Variables

Private values include things like:

• Secret keys
• Database credentials
• JWT secrets
• API private tokens

Do not put them in the same .env file as your public variables.

Instead, create another file such as .env.local.

Example:

MY_API_SECRET_KEY=my-secret-key

⚠️ Important Security Rule

Never use the NEXT_PUBLIC_ prefix for private variables.

Also, never copy .env.local inside your Docker image.

Do not do this in your Dockerfile:

#NEVER DO THAT, NEVER, NEVER, NEVER 😉
COPY .env.local .env.local

Correct Docker Compose Setup

Inject private variables at runtime using docker-compose.yaml.

Example:

env_file:
  - .env.local

If the file is located elsewhere:

env_file:
  - ./path/.env.local

Then you can access your private variables only on the server side:

process.env.MY_API_SECRET_KEY

Common Mistake

A lot of “undefined” errors happen because developers forget where the code is running.

Before debugging, always check whether your file is:

• Client side
• Server side

Client components only have access to variables prefixed with NEXT_PUBLIC_.

Server-side code can access private environment variables.

Final Advice

Here is the setup that worked reliably for me:

• Public variables → .env + NEXT_PUBLIC_ + COPY in Dockerfile
• Private variables → .env.local + env_file in Docker Compose
• Never mix public and private variables in the same file
• Never expose secrets with NEXT_PUBLIC_

Hope this saves you some debugging time.

See you soon in another bug. This is our life 🙂

~ Oswald #ZaNuVi