A Dockerfile ARG is empty or not substituted inside RUN
RUN 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.
Fix it fast
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}]"2Match what you see, then jump to its fix
- 1
The 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
The output contains the literal text $MY_ARGRUN is in exec form, so no shell expands the variableFix - 3
The 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
- 1
What does the error look like?
RUN echo "hello ${NAME}!" prints: hello !RUN [ "echo", "$HOME" ] prints the text $HOMEThe 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)' Dockerfile2Fix
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
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 \[' Dockerfile2Fix
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
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_ARG2Fix
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_ENV3Verify
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_ENVConfirmed by docs.docker.com
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix