Docker env variables not working in containers

Your container starts, but docker exec app printenv DATABASE_URL comes back empty — or worse, the process logged a literal $DATABASE_URL straight into a connection string. Almost every "Docker env variable not working" report traces to one of eight causes: an ARG used where ENV was needed, an exec-form CMD that never runs a shell, a .env file that only feeds Compose interpolation, env-file quoting rules, multi-stage resets, or a precedence collision. None of these are bugs — they are documented Docker behaviour that bites the same way on Engine 20.10 through 28.x (current in 2026). This guide is the failure-mode companion to the Docker environment variables guide and the Docker Compose env guide; start here when something that should work doesn't.

Symptom → cause → fix at a glance

Why is my ARG empty at runtime?

Because that is exactly what ARG is for. The Dockerfile reference is blunt: "Unlike ENV, an ARG variable is not embedded in the image and is not available in the final container." An ARG lives only during the build, from its declaration line onward. ENV, by contrast, persists into every layer and is present when a container starts.

# WRONG — DATABASE_URL is build-time only, gone at runtime
ARG DATABASE_URL
CMD ["node", "server.js"]   # process.env.DATABASE_URL is undefined

# RIGHT — promote the build arg into a runtime ENV
ARG DATABASE_URL
ENV DATABASE_URL=$DATABASE_URL
CMD ["node", "server.js"]

The flip side is also true: ENV set in one place is not visible in an earlier build stage, and an ARG declared before the first FROM "can't be used in any instruction after a FROM" unless you redeclare a bare ARG inside the stage. Keep secrets out of both — ARG values surface in docker history and provenance attestations, which is why the build docs call them "inappropriate for passing secrets." Use BuildKit --mount=type=secret instead, as covered in the Docker environment variables guide.

Why does my container print $VAR literally?

This is the single most surprising Docker env gotcha, and it is not a bug. The exec form of CMD and ENTRYPOINT — the JSON array form — runs your binary directly via execve with no shell in between. The Dockerfile reference states it plainly: "Using the exec form doesn't automatically invoke a command shell. This means that normal shell processing, such as variable substitution, doesn't happen." So $PORT is handed to your program as the four characters $PORT, not its value. This is the cause behind moby/moby #42937, where ENV, ARG, and even CMD ["./${FOOBAR}"] all expand to nothing.

# WRONG — exec form, no shell: passes the literal "$PORT"
CMD ["node", "server.js", "--port", "$PORT"]

# RIGHT — explicitly run a shell so it expands
CMD ["sh", "-c", "node server.js --port $PORT"]

# BETTER — exec replaces the shell so your app stays PID 1 and gets SIGTERM
CMD ["sh", "-c", "exec node server.js --port $PORT"]

The naive fix — switching to the shell form CMD node server.js --port $PORT — also works because the shell form runs under /bin/sh -c. But the shell then becomes PID 1 and may not forward SIGTERM to your app, so graceful shutdown breaks. The exec prefix above keeps signal handling intact.

Why isn't my .env file reaching the container?

Two different things are both called ".env," and conflating them is the most common Compose ticket. The auto-loaded .env file next to your compose.yaml only feeds ${VAR} interpolation inside the YAML — it is "not automatically injected into containers." To get a value into the container you must reference it explicitly under environment: or load a file with env_file:.

# .env (interpolation only — NOT injected)
TAG=16
DATABASE_URL=postgres://db:5432/app

services:
  app:
    image: myapp:${TAG}          # .env feeds this substitution
    environment:
      - DATABASE_URL=${DATABASE_URL}   # explicit bridge into the container
    env_file:
      - ./app.env                 # this file IS injected into the container

Plain docker run has no auto-loaded .env at all — you must pass --env-file ./app.env by hand. If Compose prints WARN[0000] The "DATABASE_URL" variable is not set. Defaulting to a blank string., the interpolation source is missing, not the container config. The full breakdown of all five Compose mechanisms lives in the Docker Compose environment variables guide.

What is the interpolation and runtime precedence order?

Keep two precedence chains straight. The first decides which value fills ${VAR} when Compose parses the file; the second decides which value the container actually receives.

When a value surprises you, print the resolved truth instead of guessing:

# Compose: see every value after interpolation
docker compose config

# Running container: what it actually got
docker exec my-container printenv DATABASE_URL

# Image vs runtime: ENV baked into the image
docker inspect my-app --format '{{json .Config.Env}}'

Why are quotes or comments mangling my values?

An env file is not a shell script, and the parser differs from one tool to the next. With docker run --env-file, quotes are literal characters and only a # at the start of a line is a comment — "a # appearing anywhere else in a line is treated as part of the variable value." That asymmetry produces values you never intended.

# app.env
# docker run --env-file: NODE_ENV becomes "production" WITH the quotes
NODE_ENV="production"

# The # here is NOT a comment — TOKEN becomes: abc123 # prod key
TOKEN=abc123 # prod key

# Correct
NODE_ENV=production
TOKEN=abc123

Compose's env_file: parser is more forgiving (it strips matched quotes and honours inline comments after whitespace), so the very same file can behave differently under docker run versus docker compose. Run your file through the env validator to catch stray quotes, spaces around =, and CRLF endings before they reach a container. For the full syntax reference, see the .env file guide.

Why do my variables vanish in a multi-stage build?

Each FROM begins a fresh stage. A stage only inherits ENV "set by its parent stage or any ancestor" — and an unrelated final stage that copies artifacts with COPY --from=builder is not a descendant of the builder, so none of the builder's ENV or ARG carry over. Redeclare what the runtime stage needs.

FROM node:20 AS builder
ARG APP_VERSION=0.0.0
ENV NODE_ENV=production
RUN npm run build

FROM node:20-slim
# The builder's ENV/ARG are NOT inherited here — redeclare them
ARG APP_VERSION=0.0.0
ENV NODE_ENV=production
ENV APP_VERSION=$APP_VERSION
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/server.js"]

When is this not actually a bug?

• Exec form not expanding variables — intentional. It keeps your app as PID 1 with correct signal handling. Reach for a shell wrapper only when you genuinely need expansion.
• ARG absent at runtime — by design, and a security feature. Build args are for build inputs, not runtime config or secrets.
• .env not auto-injected by Compose — deliberate separation of "configure the compose file" from "configure the container." Don't fight it with hacks; use env_file:.
• Secrets you can read with docker inspect — that is the system telling you env vars are the wrong home for credentials. Use Docker/BuildKit secrets instead.

Frequently Asked Questions

References

• Dockerfile reference — ARG, ENV, CMD, ENTRYPOINT — ARG vs ENV scope, exec vs shell form variable substitution, multi-stage inheritance.
• Docker build — build arguments and variables — why ARG values are not present in containers and unfit for secrets.
• docker run CLI reference — --env and --env-file — -e with no value, and the env-file quoting and comment rules.
• Compose — variable interpolation — .env feeds interpolation only; shell > --env-file > .env precedence.
• Compose — environment variable precedence — authoritative order when a variable is defined in multiple places.
• moby/moby #42937 — variables not expanded in CMD — the canonical report of exec-form CMD not substituting ENV/ARG values.