Skip to content

Docker build fails: base image not found

Quick summary

Your Docker build fails — the base image in the FROM instruction does not exist or cannot be accessed.

Why this happens

  • The base image name is misspelled or the tag does not exist in the registry

  • The registry is private and authentication is not configured

  • The registry is unreachable due to network issues or rate limiting

Minimal example

✗ Broken code
FROM node:18-alpine3.99 # tag does not exist
WORKDIR /app
COPY . .
RUN npm install
✓ Fixed code
FROM node:18-alpine # valid tag
WORKDIR /app
COPY . .
RUN npm install

Using a valid base image tag (node:18-alpine) that exists in the registry allows the build to proceed.

How to diagnose

  • Verify the image name and tag exist in the registry with docker pull

  • Check if the registry is private and requires authentication

  • Test network connectivity to the registry and check for rate limiting

How to fix

  • Correct the image name and tag in the Dockerfile FROM instruction

  • Add registry authentication with docker login or configure credentials in CI

  • Use a mirror or alternative registry if the original is unreachable

How to prevent

  • Pin base images to specific tags and verify they exist before building

  • Configure registry authentication in CI and use a private registry mirror

Related Resources

Related Glossary

Related Lessons

← Back to language