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

[source,docker,diff-id=1,diff-type=noncompliant]
----
ARG SETTINGS
FROM busybox
RUN ./run/setup $SETTINGS
----

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

==== Compliant solution

[source,docker,diff-id=1,diff-type=compliant]
----
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

[source,docker,diff-id=2,diff-type=noncompliant]
----
ARG SETTINGS="--default-settings"
FROM busybox
RUN ./run/setup $SETTINGS
----

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

==== Compliant solution

[source,docker,diff-id=2,diff-type=compliant]
----
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

* https://docs.docker.com/engine/reference/builder/#scope[ARG scope - Dockerfile reference]

ifdef::env-github,rspecator-view[]
'''
== Implementation Specification
(visible only on this page)

=== Message

Include the `ARG` instruction in the build stage where it is used.

=== Highlighting

Highlight usage of the variable where it is not accessible.

'''
endif::env-github,rspecator-view[]