How to fix error: build cancelled in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 184 views

The "build cancelled" or "context canceled" error occurs when Docker terminates a build process prematurely. This typically happens due to large build contexts, file locking issues, or network interruptions.

Quick fix

Fixes error: build cancelled

node_modules/
.git/
.venv/
.idea/
*.log
dist/
build/
.npm/
__pycache__/
  1. Create or update your .dockerignore file
  2. Close applications that may be locking files
  3. Clear the Docker build cache
  4. Check your network connectivity
docker — error
node_modules/
.git/
.venv/
.idea/
*.log
dist/
build/
.npm/
__pycache__/
error: build cancelled

What this error means

The "build cancelled" error in Docker indicates that the build process was interrupted before completion. This can happen for several reasons: Docker BuildKit may cancel parallel build steps that become unnecessary due to cache hits, the build context may be too large causing Docker to timeout, files in the build context may be locked by other applications, or network issues may interrupt downloads during the build. When you see this error, Docker has terminated the build and no image will be created. The error message variants include "context canceled", "Failed to solve: Canceled: context canceled", and "CANCELED [frontend internal] load build context". Understanding the specific cause requires examining what was happening when the cancellation occurred.

Typical symptoms

  • Build stops abruptly with "build cancelled" or "context canceled" message
  • Large build context transfer shown before error (e.g., "transferring context: 12.88GB")
  • Build works when IDE or application is closed but fails while they are running
  • Build succeeds on some machines but fails on others
  • Error occurs specifically when running from a different drive than the project location (Windows)

Common causes

  1. Build context includes large directories like node_modules, .git, or virtual environments that are not in .dockerignore
  2. Files are locked by running applications such as IDEs, code editors, or development servers
  3. Network connectivity issues interrupting base image pulls or package downloads
  4. BuildKit parallel step optimization canceling unnecessary steps (normal behavior)
  5. Cross-drive builds on Windows causing unexpected context size issues
  6. Insufficient memory causing Docker to terminate the build process

How to fix "error: build cancelled"

1Create or update your .dockerignore file

Add a .dockerignore file in the same directory as your Dockerfile to exclude large directories:

bash
node_modules/
.git/
.venv/
.idea/
*.log
dist/
build/
.npm/
__pycache__/

This prevents Docker from copying unnecessary files into the build context, significantly reducing transfer time and memory usage.

2Close applications that may be locking files

IDEs like VS Code, IntelliJ, or RStudio may lock files during indexing or compilation. Close these applications before running the build:

bash
# After closing your IDE, run the build from a separate terminal
docker build -t myimage .

If you have a development server running, stop it before building.

3Clear the Docker build cache

Corrupted or stale cache can cause build issues. Clear the builder cache:

bash
docker builder prune --all

This removes all build cache. Add the -f flag to skip the confirmation prompt.

4Check your network connectivity

Test if you can pull the base image directly:

bash
docker pull <your-base-image>

If this fails, you may have network issues. Try:
- Disconnecting from VPN
- Checking proxy settings
- Flushing DNS cache: ipconfig /flushdns (Windows) or sudo systemd-resolve --flush-caches (Linux)

5Run the build from the project directory (Windows)

On Windows, running Docker build from a different drive than where your project is located can cause issues:

bash
# Navigate to your project directory first
cd D:\Projects\myapp

# Then run the build
docker build -t myimage .

Always run the build command from within the project directory.

6Increase Docker memory allocation

If builds fail during memory-intensive operations (like compiling), increase Docker's memory limit:

Docker Desktop:
1. Open Docker Desktop Settings
2. Go to Resources > Advanced
3. Increase Memory allocation
4. Apply & Restart

Linux with systemd:

bash
sudo systemctl edit docker.service

Add memory limits as needed for your system.

7Check if the cancellation is expected behavior

BuildKit may show "CANCELED" for parallel steps that become unnecessary due to cache hits. This is normal behavior:

bash
#8 CANCELED [stage-1 2/3] RUN npm install
#9 DONE [stage-1 2/3] COPY --from=cache /app/node_modules ./node_modules

If the build completes successfully and produces an image, you can safely ignore these CANCELED messages.

Advanced notes

When using BuildKit (default in Docker 23.0+), parallel step execution means you may see "CANCELED" status for steps that were superseded by cache hits. This is an optimization, not an error. However, if the entire build fails with "context canceled", check your build context size with before building. For CI/CD pipelines, ensure your runner has adequate memory and network connectivity. In Kubernetes environments, resource limits on the builder pod may need adjustment. For complex multi-stage builds, consider using to build specific stages and identify which stage causes the cancellation.

Frequently asked questions

What does "error: build cancelled" mean?
The "build cancelled" error in Docker indicates that the build process was interrupted before completion. This can happen for several reasons: Docker BuildKit may cancel parallel build steps that become unnecessary due to cache hits, the build context may be too large causing Docker to timeout, files in the build context may be locked by other applications, or network issues may interrupt downloads during the build. When you see this error, Docker has terminated the build and no image will be created.
How do I fix "error: build cancelled"?
The "build cancelled" or "context canceled" error occurs when Docker terminates a build process prematurely. This typically happens due to large build contexts, file locking issues, or network interruptions.
What causes "error: build cancelled"?
Build context includes large directories like node_modules, .git, or virtual environments that are not in .dockerignore Files are locked by running applications such as IDEs, code editors, or development servers Network connectivity issues interrupting base image pulls or package downloads
Is the "error: build cancelled" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading