How to fix ARG variable is undefined in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 188 views

This Docker build error occurs when you reference an ARG variable that hasn't been declared, or when the ARG declaration loses scope due to multi-stage builds. Fix it by declaring ARG before use and redeclaring after each FROM instruction.

Quick fix

Fixes ARG variable is undefined

FROM alpine AS base
COPY $foo .
  1. Declare ARG before using it
  2. Redeclare ARG after each FROM in multi-stage builds
  3. Handle ARG in FROM instructions correctly
  4. Pass build arguments when building
docker — error
FROM alpine AS base
COPY $foo .
ARG variable is undefined

What this error means

The "ARG variable is undefined" error in Docker indicates that you're trying to use a build argument that hasn't been properly declared or has gone out of scope. Docker's ARG instruction defines variables that users can pass at build-time using the `--build-arg` flag. This error commonly occurs in two scenarios: when you reference a variable before declaring it with ARG, or when you use multi-stage builds where each FROM instruction resets the scope of previously declared ARGs. Unlike ENV variables which persist throughout the build and into the running container, ARG variables are only available from the point they're declared until the next FROM instruction. Docker BuildKit performs stricter validation of undefined variables than the legacy builder. When BuildKit detects usage of an undeclared variable, it warns you with messages like "Usage of undefined variable '$foo'" to help catch typos and missing declarations early in the build process.

Typical symptoms

  • Build warning: 'Usage of undefined variable' followed by the variable name
  • Variable substitution results in empty string instead of expected value
  • COPY or ADD instructions fail with empty source paths
  • RUN commands fail because expected environment values are empty
  • Multi-stage builds work in first stage but ARG values disappear in subsequent stages
  • Docker build succeeds but application fails at runtime due to missing configuration

Common causes

  1. ARG variable referenced before being declared with ARG instruction
  2. Multi-stage build where ARG was declared before FROM but not redeclared after
  3. Typo in variable name when referencing (e.g., $PAHT instead of $PATH)
  4. Using ARG in FROM instruction without declaring it before FROM
  5. Passing --build-arg for a variable that isn't declared in Dockerfile
  6. ENV variable with same name overriding the ARG value
  7. Missing --build-arg flag when running docker build for required arguments

How to fix "ARG variable is undefined"

1Declare ARG before using it

Every ARG variable must be declared before it's used. Add an ARG instruction before any reference to the variable.

Incorrect:

dockerfile
FROM alpine AS base
COPY $foo .

Correct:

dockerfile
FROM alpine AS base
ARG foo
COPY $foo .

You can also provide a default value:

dockerfile
FROM alpine AS base
ARG foo=default_value
COPY $foo .
2Redeclare ARG after each FROM in multi-stage builds

In multi-stage builds, each FROM instruction starts a new build stage and resets the scope of ARG variables. You must redeclare the ARG in each stage where you need it.

Problem - ARG loses scope after FROM:

dockerfile
ARG VERSION=latest
FROM ubuntu:${VERSION}
# VERSION is still available here for FROM

ARG FILENAME
COPY ${FILENAME} /app/
# FILENAME works in this stage

FROM alpine
# FILENAME is now undefined here!
COPY ${FILENAME} /app/  # This fails

Solution - Redeclare ARG in each stage:

dockerfile
ARG VERSION=latest
FROM ubuntu:${VERSION} AS builder
ARG FILENAME
COPY ${FILENAME} /app/
RUN build-something

FROM alpine
ARG FILENAME
COPY ${FILENAME} /app/

The redeclared ARG inherits the value from --build-arg automatically.

3Handle ARG in FROM instructions correctly

If you need to use an ARG in a FROM instruction (like for dynamic base images), declare it before the FROM:

dockerfile
# Declare ARG before FROM
ARG ALPINE_VERSION=3.20
FROM alpine:${ALPINE_VERSION}

# If you need the value after FROM, redeclare it
ARG ALPINE_VERSION
RUN echo "Using Alpine ${ALPINE_VERSION}"

Note that the ARG declared before FROM is only available in the FROM instruction itself. To use it in subsequent instructions, you must redeclare it after FROM.

4Pass build arguments when building

Make sure to pass the required build arguments using the --build-arg flag:

bash
# Single argument
docker build --build-arg FILENAME=app.tar.gz -t myapp .

# Multiple arguments
docker build \
  --build-arg VERSION=1.0.0 \
  --build-arg ENV=production \
  -t myapp .

If you don't pass a value and there's no default, the ARG will be empty (not undefined, but empty string).

Using docker-compose:

yaml
services:
  app:
    build:
      context: .
      args:
        - VERSION=1.0.0
        - ENV=production
5Check for typos in variable names

Docker BuildKit can detect typos and suggest corrections. If you see a message like:

bash
Usage of undefined variable '$PAHT' (did you mean $PATH?)

Review your Dockerfile for spelling mistakes:

dockerfile
# Wrong
ARG MY_VARIABLE
RUN echo ${MY_VARAIBLE}  # Typo!

# Correct
ARG MY_VARIABLE
RUN echo ${MY_VARIABLE}

Use consistent naming conventions (e.g., all uppercase for ARG names) to reduce typo risk.

6Avoid ARG/ENV naming conflicts

Environment variables defined with ENV always override ARG instructions with the same name. This can cause unexpected behavior:

dockerfile
FROM alpine
ARG MY_VAR=from_arg
ENV MY_VAR=from_env

# MY_VAR will always be "from_env", not what you pass via --build-arg
RUN echo ${MY_VAR}

Solution: Use different names for ARG and ENV, or explicitly set ENV from ARG:

dockerfile
FROM alpine
ARG BUILD_VERSION=1.0.0
ENV APP_VERSION=${BUILD_VERSION}

RUN echo "Build version: ${BUILD_VERSION}"
RUN echo "App version: ${APP_VERSION}"
7Use default values for optional arguments

Always provide sensible default values for ARG instructions that should work without --build-arg:

dockerfile
FROM node:18

# Required arg - will be empty if not provided
ARG APP_ENV

# Optional args with defaults
ARG NODE_ENV=production
ARG PORT=3000
ARG LOG_LEVEL=info

ENV NODE_ENV=${NODE_ENV}
ENV PORT=${PORT}
ENV LOG_LEVEL=${LOG_LEVEL}

For truly required arguments, add validation:

dockerfile
ARG REQUIRED_VAR
RUN test -n "${REQUIRED_VAR}" || (echo "REQUIRED_VAR must be set" && exit 1)

Advanced notes

ARG vs ENV Scope:
- ARG: Available only during build, from declaration point until next FROM (or end of Dockerfile)
- ENV: Available during build (after declaration) AND at container runtime
- ARG values are NOT accessible in running containers unless explicitly copied to ENV

BuildKit UndefinedVar Check:
Docker BuildKit includes a build check called UndefinedVar that validates variable declarations. It doesn't evaluate undefined variables in RUN, CMD, and ENTRYPOINT instructions using shell form, since the shell resolves those. The check helps catch typos early by suggesting similar variable names.

Predefined ARGs:
Docker has predefined ARGs that don't require declaration: HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, NO_PROXY, and their lowercase variants. These can be used without declaring them first:

dockerfile
FROM alpine
RUN wget --proxy=${HTTP_PROXY} http://example.com/file

Security Considerations:
Never pass secrets via ARG - they're visible in image history and build logs. Use Docker BuildKit's secret mounts instead:

dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
bash
docker build --secret id=mysecret,src=./secret.txt .

Frequently asked questions

What does "ARG variable is undefined" mean?
The "ARG variable is undefined" error in Docker indicates that you're trying to use a build argument that hasn't been properly declared or has gone out of scope. Docker's ARG instruction defines variables that users can pass at build-time using the --build-arg flag. This error commonly occurs in two scenarios: when you reference a variable before declaring it with ARG, or when you use multi-stage builds where each FROM instruction resets the scope of previously declared ARGs.
How do I fix "ARG variable is undefined"?
This Docker build error occurs when you reference an ARG variable that hasn't been declared, or when the ARG declaration loses scope due to multi-stage builds. Fix it by declaring ARG before use and redeclaring after each FROM instruction.
What causes "ARG variable is undefined"?
ARG variable referenced before being declared with ARG instruction Multi-stage build where ARG was declared before FROM but not redeclared after Typo in variable name when referencing (e.g., $PAHT instead of $PATH)
Is the "ARG variable is undefined" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading