Maaz Zindani

Loading the index…

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

A Dockerfile ARG is empty or not substituted inside RUN

ErrorRUN echo "hello ${NAME}!" prints: hello !

Short answer

A build argument only exists where it is declared. An ARG written above FROM is not visible inside a stage, so declare it again after FROM. Exec form RUN has no shell, so $VAR is not expanded. And an ARG is not kept in the final image, so copy it to ENV if the container needs it.

  • Applies to Docker Engine 27 and 28, BuildKit, Docker Desktop 4.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the variable from inside the failing stage, with a shell, so you see what the build really has.

    RUN echo "value is [${MY_ARG}]"
  2. 2Match what you see, then jump to its fix

    1. 1The echo prints an empty value, although the default is set at the top of the fileThe ARG was declared above FROM and never redeclared in the stageFix
    2. 2The output contains the literal text $MY_ARGRUN is in exec form, so no shell expands the variableFix
    3. 3The build step sees the value, but the running container does notThe value is needed when the container runs, but ARG is a build-time thingFix

What does the error look like?

  • RUN echo "hello ${NAME}!" prints: hello !
  • RUN [ "echo", "$HOME" ] prints the text $HOME
  • The value passed with --build-arg is empty in the build output

Cause 1 of 3

The ARG was declared above FROM and never redeclared in the stage

1Check

Look at where ARG appears relative to FROM. Docker says an ARG before FROM is outside any stage, so no instruction after FROM can use it. Only FROM lines can.

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

2Fix

Add the ARG line again inside the stage, without a value. It then takes the default or the --build-arg value.

ARG NAME="world"
FROM alpine
ARG NAME
RUN echo "hello ${NAME}!"

3Verify

Build with plain output and read the RUN line.

docker build --progress=plain --no-cache --build-arg NAME=docker .

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

RUN is in exec form, so no shell expands the variable

1Check

Exec form is the JSON array style, RUN [ "echo", "$MY_ARG" ]. Docker documents that it starts no shell, and the shell is what substitutes variables for RUN.

grep -n 'RUN \[' Dockerfile

2Fix

Use shell form, or run a shell yourself inside the array.

RUN echo "$MY_ARG"
# or, in exec form:
RUN [ "sh", "-c", "echo $MY_ARG" ]

3Verify

Rebuild with plain output and check the printed value.

docker build --progress=plain --no-cache --build-arg MY_ARG=test .

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The value is needed when the container runs, but ARG is a build-time thing

1Check

Docker describes ARG as not persisted in the final image. Only ENV values are available in containers started from the image.

docker run --rm my-image env | grep MY_ARG

2Fix

Pass the ARG into an ENV in the same stage. Remember that ENV values stay in the image and in containers, so do not put secrets there.

ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV

3Verify

Build with an override and read the variable in the container.

docker build --build-arg NODE_ENV=development -t my-image .
docker run --rm my-image env | grep NODE_ENV

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Declare ARG in the stage that uses it, and keep a default so the value is never silently empty.
  • Use shell form for RUN when it needs $VARIABLES.
  • Do not pass passwords or tokens as build arguments: Docker warns they can end up in the image metadata and history. Use secret mounts.

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.