Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A variable is set for docker build or compose, but the running container has it empty

Errorecho $MY_VAR prints an empty line inside the container

Short answer

Build arguments and runtime variables are different things. An ARG exists only while the image builds, an ENV is stored in the image, and a value you want at run time must come from ENV, docker run -e, or the environment and env_file keys in Compose. Check what the container really has first, then fix the one that is missing.

  • Applies to Docker Engine 27, Docker Compose 2.x, Dockerfile syntax 1
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what the running container actually has. This separates 'never passed' from 'passed but read wrongly'.

    docker exec <container> env
    docker inspect --format='{{json .Config}}' <container>
  2. 2Match what you see, then jump to its fix

    1. 1The Dockerfile has ARG MY_VAR and you pass --build-arg, but env inside the container lacks MY_VAR.The value was given as ARG, which is gone at run timeFix
    2. 2ARG VERSION sits above FROM, and a RUN or ENV below it sees an empty value.An ARG declared before FROM is not visible in the stageFix
    3. 3docker compose up starts the service, and docker compose exec <service> env lacks the key.Compose does not pass the variable to the serviceFix
    4. 4The variable exists in env, but CMD ["echo", "$MY_VAR"] prints the text $MY_VAR.The exec form does not expand the variableFix

What does the error look like?

  • echo $MY_VAR prints an empty line inside the container
  • process.env.MY_VAR is undefined in the running app

Cause 1 of 4

The value was given as ARG, which is gone at run time

1Check

Build arguments are not present in containers unless the Dockerfile explicitly passes them into the image. ENV values, in contrast, persist in containers created from the image.

grep -n -E "^(ARG|ENV)" Dockerfile

2Fix

Copy the argument into an ENV in the same stage, or pass the value when you run the container.

ARG MY_VAR=default
ENV MY_VAR=$MY_VAR

# or at run time
docker run -e MY_VAR=value my-image

3Verify

Start a new container from the rebuilt image and print the variable.

docker run --rm my-image printenv MY_VAR

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

An ARG declared before FROM is not visible in the stage

1Check

Global ARGs declared before FROM are not automatically inherited by a build stage. To use one inside a stage you consume it there with ARG NAME.

grep -n -E "^(ARG|FROM)" Dockerfile

2Fix

Redeclare the argument after FROM in every stage that needs it.

ARG NODE_VERSION=22
FROM node:${NODE_VERSION}
ARG NODE_VERSION
ENV NODE_VERSION=$NODE_VERSION

3Verify

Rebuild and print the value inside the new container.

docker run --rm my-image printenv NODE_VERSION

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

Compose does not pass the variable to the service

1Check

Compose sets container variables with the environment attribute or an env_file. Listing only a name, such as - DEBUG, takes the value from your shell, and no warning is issued when it is not set there.

docker compose config

2Fix

Give the variable a value in the file, or load it from an env file whose path is relative to compose.yaml.

services:
  webapp:
    environment:
      DEBUG: "true"
    env_file:
      - webapp.env

3Verify

Recreate the service and print the variable.

docker compose up -d --force-recreate webapp
docker compose exec webapp printenv DEBUG

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

The exec form does not expand the variable

1Check

The exec form does not invoke a command shell, so variable substitution does not happen. The shell form runs through /bin/sh -c.

grep -n -E "^(CMD|ENTRYPOINT|RUN)" Dockerfile

2Fix

Use the shell form, or call a shell yourself in the exec form.

CMD echo "$MY_VAR"
# or
CMD ["sh", "-c", "echo \"$MY_VAR\""]

3Verify

Run the container and read the output.

docker run --rm my-image

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Decide for each value whether it is needed at build time (ARG) or run time (ENV, -e, Compose), and name it that way in the file.
  • Do not pass secrets as build arguments or ENV; the Docker docs say they are exposed in the final image. Use secret mounts.
  • Add docker compose config to your checks, so you see the final values before you start anything.

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.