How to fix ARG variable is undefined in Docker

DockerBEGINNERLOW

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 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.

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)

How to fix ARG variable is undefined in Docker

What this error means

Typical symptoms

Common causes

How to fix "ARG variable is undefined"

Advanced notes

Related errors

Official resources & further reading