How to fix failed to process "FROM ${BASE_IMAGE}": no build argument in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 188 views

This Docker build error occurs when a Dockerfile uses an ARG variable in the FROM instruction but the argument was not provided via --build-arg and has no default value. Fix it by providing a default value for the ARG or passing the build argument at build time.

Quick fix

Fixes failed to process "FROM ${BASE_IMAGE}": no build argument

ARG BASE_IMAGE
FROM ${BASE_IMAGE}
  1. Add a default value to your ARG instruction
  2. Provide the build argument at build time
  3. Verify ARG is declared before FROM
  4. Check for typos in variable names
docker — error
ARG BASE_IMAGE
FROM ${BASE_IMAGE}
failed to process "FROM ${BASE_IMAGE}": no build argument

What this error means

The "no build argument" error for FROM in Docker indicates that your Dockerfile uses a variable in the FROM instruction (like `FROM ${BASE_IMAGE}`) but Docker cannot resolve what value to use for that variable. When you declare an ARG before FROM and use it in the FROM instruction to dynamically select the base image, Docker requires that variable to have a value at build time. This value can come from either: 1. A default value declared in the ARG instruction itself 2. A `--build-arg` flag passed to the `docker build` command If neither is provided, Docker cannot determine which base image to pull and the build fails immediately. This is by design - Docker's build check called "InvalidDefaultArgInFrom" enforces that a Dockerfile should be buildable without requiring `--build-arg` flags, meaning your ARG should have a sensible default value.

Typical symptoms

  • Docker build fails immediately at the FROM instruction
  • Error message contains 'failed to process' and 'no build argument'
  • Build works locally with --build-arg but fails in CI/CD pipelines where the argument is missing
  • Dockerfile that previously worked fails after removing environment variables or build configurations
  • Multi-arch or parameterized builds fail when base image variable is not set

Common causes

  1. ARG variable used in FROM instruction has no default value and --build-arg was not provided
  2. ARG instruction placed after FROM instead of before it (ARG scope issue)
  3. Typo in the ARG variable name between declaration and usage in FROM
  4. Build system or CI/CD pipeline not passing the required --build-arg flag
  5. Environment variable substitution syntax used instead of ARG (${VAR} without ARG declaration)
  6. Using shell variable syntax instead of Docker ARG syntax in the Dockerfile

How to fix "failed to process "FROM ${BASE_IMAGE}": no build argument"

1Add a default value to your ARG instruction

The recommended fix is to provide a sensible default value for your ARG so the build works without requiring --build-arg:

Before (broken):

dockerfile
ARG BASE_IMAGE
FROM ${BASE_IMAGE}

After (fixed):

dockerfile
ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

This way, if no --build-arg BASE_IMAGE=... is provided, Docker uses the default value ubuntu:22.04. You can still override it at build time:

bash
docker build --build-arg BASE_IMAGE=alpine:3.18 -t myapp .
2Provide the build argument at build time

If you intentionally want to require the build argument (no default), pass it with --build-arg:

bash
docker build --build-arg BASE_IMAGE=python:3.11-slim -t myapp .

For multiple build arguments:

bash
docker build \
  --build-arg BASE_IMAGE=node:20-alpine \
  --build-arg APP_VERSION=1.0.0 \
  -t myapp .

Important: Do not add spaces around the equals sign. Use KEY=value, not KEY = value.

3Verify ARG is declared before FROM

The ARG instruction must appear BEFORE the FROM instruction to be used in it:

Incorrect (ARG after FROM):

dockerfile
FROM ${BASE_IMAGE}
ARG BASE_IMAGE=ubuntu:22.04

Correct (ARG before FROM):

dockerfile
ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

Note: ARG is the ONLY instruction allowed before FROM. All other instructions (ENV, RUN, LABEL, etc.) must come after FROM.

4Check for typos in variable names

Ensure the variable name in the ARG declaration exactly matches the usage in FROM:

Wrong (typo):

dockerfile
ARG BASE_IMG=ubuntu:22.04
FROM ${BASE_IMAGE}

Correct:

dockerfile
ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

Variable names are case-sensitive, so BASE_IMAGE and base_image are different variables.

5Re-declare ARG after FROM if needed later

Important: An ARG declared before FROM is ONLY available in the FROM instruction itself. After FROM, the ARG value is lost and must be re-declared:

dockerfile
ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

# This ARG re-declaration is needed to use the value after FROM
ARG BASE_IMAGE
RUN echo "Built from: ${BASE_IMAGE}"

The re-declared ARG inherits the value passed via --build-arg but does NOT inherit the default value. If you need the default after FROM:

dockerfile
ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

ARG BASE_IMAGE=ubuntu:22.04
RUN echo "Built from: ${BASE_IMAGE}"
6Update CI/CD pipeline configuration

If builds work locally but fail in CI/CD, ensure your pipeline passes the required build arguments.

GitHub Actions:

yaml
- name: Build Docker image
  run: |
    docker build \
      --build-arg BASE_IMAGE=${{ vars.BASE_IMAGE }} \
      -t myapp .

GitLab CI:

yaml
build:
  script:
    - docker build --build-arg BASE_IMAGE=$BASE_IMAGE -t myapp .
  variables:
    BASE_IMAGE: "ubuntu:22.04"

Docker Compose:

yaml
services:
  app:
    build:
      context: .
      args:
        BASE_IMAGE: ubuntu:22.04

Advanced notes

Why Docker requires defaults for ARG in FROM:
Docker's build check "InvalidDefaultArgInFrom" enforces that Dockerfiles should be buildable without external configuration. This ensures:
- Reproducible builds across different environments
- Clearer documentation of which base images are supported
- Easier debugging when builds fail

Multi-stage builds and ARG scope:
In multi-stage builds, each FROM starts a new build stage. An ARG declared before the first FROM can only be used in FROM instructions, not within stages:

dockerfile
ARG BASE_VERSION=22.04
FROM ubuntu:${BASE_VERSION} AS builder
# ARG BASE_VERSION is NOT available here

FROM ubuntu:${BASE_VERSION} AS runner
# Still accessible in any FROM, but not inside stages
ARG BASE_VERSION
# Now it's available in this stage

Security considerations:
Build arguments passed via --build-arg are visible in the image history. For sensitive values:
- Use Docker secrets instead of build arguments
- Consider multi-stage builds where secrets are only in the builder stage
- Use --secret flag with BuildKit for true secret handling

bash
# Using BuildKit secrets (more secure)
docker build --secret id=mysecret,src=secret.txt -t myapp .

Validating required build arguments:
If you truly want to make a build argument mandatory (fail fast with a clear error), add validation:

dockerfile
ARG BASE_IMAGE
FROM ${BASE_IMAGE:-scratch}
ARG BASE_IMAGE
RUN test -n "${BASE_IMAGE}" || (echo "BASE_IMAGE is required" && exit 1)

Frequently asked questions

What does "failed to process "FROM ${BASE_IMAGE}": no build argument" mean?
The "no build argument" error for FROM in Docker indicates that your Dockerfile uses a variable in the FROM instruction (like FROM ${BASE_IMAGE}) but Docker cannot resolve what value to use for that variable. When you declare an ARG before FROM and use it in the FROM instruction to dynamically select the base image, Docker requires that variable to have a value at build time. This value can come from either: 1.
How do I fix "failed to process "FROM ${BASE_IMAGE}": no build argument"?
This Docker build error occurs when a Dockerfile uses an ARG variable in the FROM instruction but the argument was not provided via --build-arg and has no default value. Fix it by providing a default value for the ARG or passing the build argument at build time.
What causes "failed to process "FROM ${BASE_IMAGE}": no build argument"?
ARG variable used in FROM instruction has no default value and --build-arg was not provided ARG instruction placed after FROM instead of before it (ARG scope issue) Typo in the ARG variable name between declaration and usage in FROM
Is the "failed to process "FROM ${BASE_IMAGE}": no build argument" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading