GitHub Actions "Dockerfile-based action ... build failed"

A step using a Dockerfile-based action fails during "Build container for action use" because the action's Dockerfile cannot build - a base image that will not pull, a failing build command, or a platform mismatch.

What this error means

The run fails before the action does anything, during the container build phase, with a docker build error referencing the action's Dockerfile rather than your code.

Build container for action use: '.github/actions/tool/Dockerfile'.
ERROR: failed to solve: process "/bin/sh -c make" did not complete: exit code 1
Error: Docker build failed with exit code 1

Common causes

The action Dockerfile fails to build

A RUN command in the action's Dockerfile fails, a referenced file is missing from the build context, or the base image cannot be pulled (auth/rate limit).

Platform or runner mismatch

A Dockerfile action only runs on Linux runners, and an image built for the wrong architecture or needing buildx features can fail on the default builder.

How to fix it

Build the action image locally first

Reproduce the action's build outside Actions to find the failing layer.

docker build -f .github/actions/tool/Dockerfile .github/actions/tool
# fix the failing RUN / missing file, then re-run the workflow

Fix context, base image, and platform

1. Ensure every file the Dockerfile COPYs exists in the action directory (the build context).
2. Authenticate to the base-image registry if pulls are denied or rate-limited.
3. Run Dockerfile-based actions on a Linux runner; use a prebuilt image if the build is heavy.

How to prevent it

• Test action Dockerfiles with a local docker build in CI.
• Keep the build context minimal and ensure COPYed files exist.
• Run Docker-based actions on Linux and authenticate base-image pulls.

Related guides