The variable is not available in the current scope. It will be evaluated to an empty value.

Why is this an issue?

The variables defined by ARG instruction have a scope from the definition to the end of the build stage where it was defined. If it was defined in the beginning of the Dockerfile (outside of any build stage), then its scope is restricted to only FROM instructions. Outside of their scope, variables will be resolved to empty string which may lead to unintended behaviour.

How to fix it

Code examples

Noncompliant code example

ARG SETTINGS
FROM busybox
RUN ./run/setup $SETTINGS

In this case the $SETTINGS variable will be evaluated to empty string.

Compliant solution

FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

In this case when Dockerfile will be built with the flag --build-arg SETTINGS=--some-settings the flag --some-settings will be passed to the RUN instruction.

Noncompliant code example

ARG SETTINGS="--default-settings"
FROM busybox
RUN ./run/setup $SETTINGS

In this case the $SETTINGS variable will be evaluated to empty string.

Compliant solution

ARG SETTINGS="--default-settings"
FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

In this case the flag --default-settings will be passed to RUN instruction (unless another value is provided during build time).

How does this work?

The FROM instruction starts a new build stage where variables defined by previous ARG instructions are out of this new scope. To make it accessible for the build stage they need to be defined after the FROM instruction.

Resources

Documentation