This Docker build error occurs when a required ARG instruction in your Dockerfile is not provided a value during the build process. The fix involves passing the missing argument using the --build-arg flag or providing a default value in the Dockerfile.
The "required build argument not set" error indicates that your Dockerfile declares an ARG (build argument) that expects a value, but no value was provided when running the docker build command. This typically happens when the Dockerfile uses an ARG without a default value, and the build process enforces that the argument must be supplied. In Docker, the ARG instruction defines a variable that users can pass at build-time using the `--build-arg <varname>=<value>` flag. Unlike ENV variables, ARG values are only available during the build process and are not persisted in the final image. When an ARG is declared without a default value and is used in validation logic (like a `test -n` check), the build will fail if the argument is not provided. This error is often intentional behavior in Dockerfiles that require certain configuration values (like API keys, version numbers, or environment-specific settings) to be explicitly provided at build time rather than using defaults that might be forgotten to update.
First, examine your Dockerfile to find which ARG is required. Look for ARG instructions without default values:
# This ARG has no default and requires a value
ARG MY_API_KEY
# This ARG has a default and is optional
ARG VERSION=latestAlso look for validation checks that enforce required arguments:
ARG MY_VARIABLE
RUN test -n "$MY_VARIABLE" || (echo "MY_VARIABLE is required" && exit 1)Provide the required argument when building your image:
# Single argument
docker build --build-arg MY_API_KEY=your_value -t myimage .
# Multiple arguments
docker build \
--build-arg MY_API_KEY=your_value \
--build-arg VERSION=1.2.3 \
-t myimage .Make sure the argument name matches exactly (case-sensitive) with the ARG in your Dockerfile.
If the argument should have a sensible default, add it to the Dockerfile:
# Before: requires value at build time
ARG CONFIGURATION
# After: has default, can be overridden
ARG CONFIGURATION=ReleaseThis makes the argument optional while still allowing it to be overridden:
# Uses default value "Release"
docker build -t myimage .
# Overrides with "Debug"
docker build --build-arg CONFIGURATION=Debug -t myimage .If your ARG is declared before the FROM instruction, it won't be available after FROM. Each build stage has its own scope:
Problem:
ARG VERSION=latest
FROM ubuntu:${VERSION}
# VERSION is not available here!
RUN echo "Version: $VERSION" # This will be emptySolution:
ARG VERSION=latest
FROM ubuntu:${VERSION}
ARG VERSION # Redeclare to use in this stage
RUN echo "Version: $VERSION" # Now works correctlyIn multi-stage builds, redeclare the ARG in each stage where you need it.
When using docker-compose, specify build arguments in your docker-compose.yml:
version: "3.9"
services:
myapp:
build:
context: .
dockerfile: Dockerfile
args:
- MY_API_KEY=${MY_API_KEY}
- VERSION=1.2.3
# Or using mandatory variable syntax
services:
myapp:
build:
context: .
args:
- MY_API_KEY=${MY_API_KEY:?Error: MY_API_KEY must be set}Then set environment variables before building:
export MY_API_KEY=your_value
docker-compose buildFor sensitive values like API keys, avoid hardcoding them. Use environment variables:
# Set in your shell or CI/CD environment
export API_KEY="your_secret_key"
# Pass to docker build
docker build --build-arg API_KEY="$API_KEY" -t myimage .In CI/CD pipelines (GitHub Actions example):
- name: Build Docker image
run: |
docker build \
--build-arg API_KEY=${{ secrets.API_KEY }} \
-t myimage .Security note: Build arguments are visible in the image history. For truly sensitive values, consider using Docker BuildKit secrets instead.
Ensure your argument values are properly quoted, especially if they contain special characters:
# Values with spaces or special characters need quotes
docker build --build-arg MESSAGE="Hello World" -t myimage .
# Values with dollar signs need single quotes or escaping
docker build --build-arg PRICE='$100' -t myimage .In the Dockerfile, use double quotes when referencing ARGs in RUN commands:
ARG CONFIGURATION=Debug
RUN dotnet publish "Project.csproj" -c "$CONFIGURATION" -o /app/publishMaking Build Arguments Mandatory:
You can enforce required build arguments by adding validation in your Dockerfile:
ARG MY_REQUIRED_ARG
RUN test -n "$MY_REQUIRED_ARG" || (echo "Error: MY_REQUIRED_ARG is required" && exit 1)Or using shell parameter expansion:
ARG MY_REQUIRED_ARG
RUN /bin/bash -c ': ${MY_REQUIRED_ARG:?Build argument MY_REQUIRED_ARG is required}'ARG Scope and Multi-Stage Builds:
- ARGs declared before the first FROM are "global" and can be used in FROM instructions
- After each FROM, a new build stage begins with a fresh scope
- To use a global ARG in a stage, redeclare it (without a value) after FROM
- Each stage can have its own default value: ARG VERSION=1.0 in stage 1 and ARG VERSION=2.0 in stage 2
BuildKit Secret Mounts (Better for Sensitive Data):
For sensitive values like SSH keys or API tokens, use BuildKit secret mounts instead of ARG:
# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecretdocker build --secret id=mysecret,src=./secret.txt -t myimage .This keeps secrets out of the build cache and image history.
Debugging ARG Issues:
View the values Docker is using during build:
# Enable plain progress output
BUILDKIT_PROGRESS=plain docker build --build-arg MY_ARG=value -t myimage .
# Add a debug RUN command temporarily
RUN echo "MY_ARG value is: $MY_ARG"dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec