How to fix ERROR: Service 'app' failed to build in Docker

The "Service failed to build" message appears at the end, but the actual error is in the preceding output. Scroll up in your terminal to find lines like:

Step 5/10 : COPY package.json .
COPY failed: file not found in build context

or

E: Unable to locate package some-package
The command '/bin/sh -c apt-get install some-package' returned a non-zero code: 100

This specific error tells you exactly what went wrong.

Check your Dockerfile for common syntax issues:

# WRONG - RUN on same line as package name
RUN apt-get install -y python3 RUN pip install flask

# CORRECT - Each RUN is a separate command
RUN apt-get install -y python3
RUN pip install flask

Also verify that:
- Each instruction (FROM, RUN, COPY, etc.) is on its own line
- Multi-line commands use \ for line continuation
- There are no invisible characters or encoding issues

Files in COPY and ADD commands must exist relative to the build context. In docker-compose.yml:

services:
  app:
    build:
      context: ./my-app      # Build context directory
      dockerfile: Dockerfile  # Relative to context

If your Dockerfile contains COPY package.json ., then package.json must exist in ./my-app/.

Run this to verify:

ls -la ./my-app/package.json

If you have a .dockerignore file, it might be excluding files your build needs:

cat .dockerignore

Common problematic patterns:

# This excludes ALL files starting with "."
.*

# This might exclude needed config files
*.json

Temporarily rename or remove .dockerignore to test if it's the cause.

If the build fails with exit code 137 or mentions memory issues:

Docker Desktop (Windows/Mac):
1. Open Docker Desktop Settings
2. Go to Resources > Advanced
3. Increase Memory to at least 4GB
4. Click "Apply & Restart"

Linux:
Check available memory:

free -h
docker info | grep -i memory

If low, close other applications or add swap space.

Stale caches or low disk space can cause build failures:

# Remove unused containers, networks, images
docker system prune -a

# Check disk space
docker system df

# Force rebuild without cache
docker-compose build --no-cache

If disk space is critically low, consider removing old images:

docker image prune -a

Build the image directly with Docker to get more detailed output:

# Navigate to the build context directory
cd ./my-app

# Build with verbose output
docker build -t test-build . 2>&1 | tee build.log

This often provides clearer error messages than docker-compose.