How to fix error checking context: context too large in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 185 views

Docker fails when the build context exceeds size limits. This happens when large files or directories like node_modules, .git, or logs are inadvertently included. Create a .dockerignore file to exclude unnecessary files.

Quick fix

Fixes error checking context: context too large

# See what Docker reports as context size
docker build . 2>&1 | head -5

# Check directory size manually
du -sh .

# Find the largest directories
du -h --max-depth=1 . | sort -hr | head -10
  1. Check current build context size
  2. Create a .dockerignore file
  3. Add common exclusions to .dockerignore
  4. Exclude project-specific large files
docker — error
# See what Docker reports as context size
docker build . 2>&1 | head -5
# Check directory size manually
du -sh .
# Find the largest directories
du -h --max-depth=1 . | sort -hr | head -10
error checking context: context too large

What this error means

When you run `docker build`, Docker packages all files in your build directory (the "build context") and sends them to the Docker daemon. The "context too large" error occurs when this context exceeds the daemon's configured size limit or available memory. The build context includes every file and subdirectory in your Dockerfile's directory by default. This means version control folders (`.git`), dependency directories (`node_modules`, `vendor`), build artifacts, logs, and temporary files all get packaged and transferred—even if your Dockerfile never uses them. This error is common in projects with large repositories, many dependencies, or when running Docker builds from a directory containing unrelated large files. The solution is to exclude unnecessary files using a `.dockerignore` file.

Typical symptoms

  • Docker build hangs at "Sending build context to Docker daemon"
  • Build context shows unexpectedly large size (e.g., 5GB+ when expecting <100MB)
  • Docker build fails with "context too large" or memory errors
  • Builds are extremely slow even for small Dockerfile changes
  • Docker daemon runs out of disk space during builds
  • CI/CD pipelines timeout during the context transfer phase

Common causes

  1. Missing .dockerignore file allowing all files to be included in context
  2. .git directory included in build context (can be several GB with history)
  3. node_modules or other dependency directories included unnecessarily
  4. Large log files, data files, or database dumps in the build directory
  5. Build artifacts from previous builds (.vagrant, dist/, build/)
  6. Running docker build from a parent directory containing many projects

How to fix "error checking context: context too large"

1Check current build context size

Before making changes, measure your current build context size:

bash
# See what Docker reports as context size
docker build . 2>&1 | head -5

# Check directory size manually
du -sh .

# Find the largest directories
du -h --max-depth=1 . | sort -hr | head -10

This helps identify which directories are contributing most to the context size.

2Create a .dockerignore file

Create a .dockerignore file in your project root (same directory as your Dockerfile):

bash
touch .dockerignore

This file uses the same syntax as .gitignore and tells Docker which files to exclude from the build context.

3Add common exclusions to .dockerignore

Add these common patterns to your .dockerignore:

bash
# Version control
.git
.gitignore
.svn

# Dependencies (will be installed fresh in container)
node_modules
vendor
.venv
__pycache__

# Build artifacts
dist
build
*.egg-info

# IDE and editor files
.idea
.vscode
*.swp
*.swo
.DS_Store

# Logs and temp files
*.log
logs
tmp
temp

# Docker files (not needed in context)
Dockerfile
docker-compose*.yml
.dockerignore

# CI/CD
.github
.gitlab-ci.yml
.travis.yml

# Testing
coverage
.nyc_output
*.test.js
*.spec.js

# Documentation
docs
*.md
README*

# Environment and secrets
.env*
*.pem
*.key
4Exclude project-specific large files

Identify and exclude files specific to your project:

bash
# Find large files in your project
find . -type f -size +10M -exec ls -lh {} \;

# Find large directories
du -h --max-depth=2 . | sort -hr | head -20

Add any large files or directories to your .dockerignore:

bash
# Project-specific
data/
*.sql
*.dump
*.tar.gz
backups/
.vagrant/
5Verify excluded files are not copied in Dockerfile

Ensure your Dockerfile doesn't explicitly copy files you've excluded. If you need certain files, use exceptions:

bash
# In .dockerignore - exclude all markdown except README
*.md
!README.md

# Exclude all in docs except API docs
docs/*
!docs/api/

The ! prefix creates exceptions to exclusion rules. Rules are processed top-to-bottom, so place exceptions after the exclusion.

6Test the reduced context size

After creating your .dockerignore, verify the improvement:

bash
# Rebuild and check context size
docker build . 2>&1 | head -5

# Compare with previous size
# You should see a significant reduction

A well-configured .dockerignore can reduce context from gigabytes to megabytes.

7Use a dedicated build directory (alternative approach)

For complex projects, consider building from a subdirectory:

bash
# Create a dedicated docker build directory
mkdir -p docker-build
cp Dockerfile docker-build/
cp -r src docker-build/
cp package.json docker-build/

cd docker-build && docker build -t myapp .

Or specify the build context explicitly:

bash
# Build with Dockerfile in current dir, but context from subdirectory
docker build -f ./Dockerfile ./src
8Debug remaining context issues

If context is still large, debug what's being included:

bash
# Use docker-show-context tool
docker build -t docker-show-context https://github.com/pwaller/docker-show-context.git
docker run -v ${PWD}:/context docker-show-context

# Or simulate with tar (shows what would be sent)
tar -cvf - --exclude-from=.dockerignore . | wc -c

This reveals exactly which files are included in your build context.

Advanced notes

### Multi-Dockerfile Projects

If you have multiple Dockerfiles, you can create specific ignore files for each:
- Dockerfile.dev.dockerignore for docker build -f Dockerfile.dev
- Dockerfile.prod.dockerignore for docker build -f Dockerfile.prod

Docker automatically looks for <dockerfile-name>.dockerignore before falling back to .dockerignore.

### BuildKit Considerations

Docker BuildKit (enabled by default in newer Docker versions) handles context more efficiently, but .dockerignore is still essential:

bash
# Force BuildKit for better performance
DOCKER_BUILDKIT=1 docker build .

### Security Implications

Always exclude sensitive files from build context, even if your Dockerfile doesn't copy them. The entire context is sent to the daemon, and in remote build scenarios, this could expose secrets:

bash
# Always exclude these
.env*
*.pem
*.key
.aws/
.ssh/
credentials*

### CI/CD Optimization

In CI pipelines, the build context transfer can be a bottleneck. Consider:
1. Using multi-stage builds to reduce final image size
2. Caching dependency layers separately
3. Using .dockerignore aggressively to minimize transfer time

Frequently asked questions

What does "error checking context: context too large" mean?
When you run docker build, Docker packages all files in your build directory (the "build context") and sends them to the Docker daemon. The "context too large" error occurs when this context exceeds the daemon's configured size limit or available memory. The build context includes every file and subdirectory in your Dockerfile's directory by default.
How do I fix "error checking context: context too large"?
Docker fails when the build context exceeds size limits. This happens when large files or directories like node_modules, .git, or logs are inadvertently included. Create a .dockerignore file to exclude unnecessary files.
What causes "error checking context: context too large"?
Missing .dockerignore file allowing all files to be included in context .git directory included in build context (can be several GB with history) node_modules or other dependency directories included unnecessarily
Is the "error checking context: context too large" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading