How to fix Error response from daemon: repository does not exist in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 219 views

The 'repository does not exist' error occurs when Docker cannot find an image locally that matches the tag you are trying to push. This typically happens when the image is not tagged correctly with your Docker Hub username or registry URL, or when the image simply does not exist locally.

Quick fix

Fixes Error response from daemon: repository does not exist

# List all local images
docker images

# Search for a specific image
docker images | grep myimage

# Show full image details including digests
docker images --no-trunc
  1. List local images to verify the image exists
  2. Tag the image with your Docker Hub username
  3. Build the image if it does not exist locally
  4. Check for typos in the image name
docker — error
# List all local images
docker images
# Search for a specific image
docker images | grep myimage
# Show full image details including digests
docker images --no-trunc
Error response from daemon: repository does not exist

What this error means

This error message appears when the Docker daemon cannot locate a local image matching the repository name you specified in the push command. Unlike authentication errors, this error indicates that Docker never even attempted to contact the registry because it could not find the image to push in the first place. The Docker push command requires an image to exist locally with an exact tag match. When you run `docker push username/myimage:latest`, Docker looks for a local image with that exact name and tag. If no matching image exists, it reports "repository does not exist" because from Docker's perspective, there is nothing to push. This error commonly occurs due to: 1. **Incorrect tagging** - The image was built or pulled with a different name than what you are trying to push 2. **Missing username prefix** - The image was tagged without your Docker Hub username in the namespace 3. **Typos** - Simple misspellings in the image name, username, or tag 4. **Image not built** - The image was never created in the first place, often in CI/CD pipelines where build steps fail silently

Typical symptoms

  • Docker push fails with 'repository does not exist' or 'An image does not exist locally with the tag'
  • Push command exits immediately without showing any upload progress
  • Error message includes 'The push refers to repository [docker.io/username/image]'
  • Docker build succeeds but push fails with this error
  • CI/CD pipeline fails at the push step despite earlier build appearing successful
  • Error occurs when pushing after pulling from a different registry

Common causes

  1. Image tagged without Docker Hub username (e.g., 'myimage' instead of 'username/myimage')
  2. Typo in the image name, username, or tag when running docker push
  3. Image was never built or was built with a different name
  4. Running docker push before docker build completed
  5. Using a different image name in docker push than was used in docker build
  6. Multi-stage build did not export the final image with the expected name
  7. Docker Compose service built with a different image name than expected
  8. Local image was removed or pruned before push

How to fix "Error response from daemon: repository does not exist"

1List local images to verify the image exists

First, check what images exist locally and confirm the exact name and tag:

bash
# List all local images
docker images

# Search for a specific image
docker images | grep myimage

# Show full image details including digests
docker images --no-trunc

Look for your image in the output. The REPOSITORY column shows the full image name including any namespace. If your image is not listed, you need to build it first.

2Tag the image with your Docker Hub username

If the image exists but without your username, tag it correctly:

bash
# Tag an existing image with your Docker Hub username
docker tag myimage:latest YOUR_DOCKERHUB_USERNAME/myimage:latest

# Verify the new tag was created
docker images | grep myimage

# Now push the correctly tagged image
docker push YOUR_DOCKERHUB_USERNAME/myimage:latest

Replace YOUR_DOCKERHUB_USERNAME with your actual Docker Hub username. After tagging, both the original name and the new tagged name will appear in docker images - they reference the same image.

3Build the image if it does not exist locally

If the image is not in your local Docker images list, you need to build it:

bash
# Build with the correct tag from the start
docker build -t YOUR_DOCKERHUB_USERNAME/myimage:latest .

# Or build with a Dockerfile in a different location
docker build -t YOUR_DOCKERHUB_USERNAME/myimage:latest -f path/to/Dockerfile .

# Verify the image was created
docker images YOUR_DOCKERHUB_USERNAME/myimage

Building with the correct tag from the start avoids the need for a separate tagging step.

4Check for typos in the image name

Carefully compare the image name in your push command with the actual local image:

bash
# Show exact image names
docker images --format "{{.Repository}}:{{.Tag}}"

# Common typo examples to watch for:
# - 'pyhon' instead of 'python'
# - 'username' vs 'user_name' (underscores vs no underscores)
# - Wrong case: 'MyImage' vs 'myimage' (Docker Hub requires lowercase)

Docker image names must be lowercase. If your image has uppercase letters, you need to rebuild or retag it with a lowercase name.

5Use the correct registry URL for private registries

If pushing to a private registry (not Docker Hub), include the full registry URL in the tag:

bash
# For a private registry
docker tag myimage:latest registry.example.com/myimage:latest
docker push registry.example.com/myimage:latest

# For Google Container Registry
docker tag myimage:latest gcr.io/PROJECT_ID/myimage:latest
docker push gcr.io/PROJECT_ID/myimage:latest

# For Amazon ECR
docker tag myimage:latest AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/myimage:latest
docker push AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/myimage:latest

# For GitHub Container Registry
docker tag myimage:latest ghcr.io/USERNAME/myimage:latest
docker push ghcr.io/USERNAME/myimage:latest

The tag must exactly match the registry URL you are pushing to.

6Fix Docker Compose image naming

When using Docker Compose, ensure the image name in your compose file matches what you are trying to push:

yaml
# docker-compose.yml
services:
  myapp:
    build: .
    image: YOUR_DOCKERHUB_USERNAME/myapp:latest

Then build and push:

bash
# Build with compose
docker compose build

# Push with compose
docker compose push

# Or push the specific image
docker push YOUR_DOCKERHUB_USERNAME/myapp:latest

If you do not specify an image name in the compose file, Docker Compose generates a name like projectname_servicename which cannot be pushed to Docker Hub.

Advanced notes

### Understanding Docker Image Naming

Docker image names follow a specific format:

bash
[registry/][namespace/]repository[:tag][@digest]

- registry: The registry hostname (defaults to docker.io for Docker Hub)
- namespace: Your username or organization (required for Docker Hub pushes)
- repository: The image name
- tag: Version identifier (defaults to 'latest')

Examples:
- nginx - Official image (no namespace needed to pull)
- username/myapp - User's image on Docker Hub
- gcr.io/project/myapp - Google Container Registry
- registry.example.com:5000/myapp - Private registry with port

### CI/CD Pipeline Considerations

In CI/CD pipelines, the "repository does not exist" error often indicates a build failure that was not properly caught:

yaml
# GitHub Actions example
jobs:
  build-and-push:
    steps:
      - name: Build image
        run: |
          docker build -t ${{ secrets.DOCKER_USERNAME }}/myapp:${{ github.sha }} .
          # Verify build succeeded
          docker images | grep myapp

      - name: Push image
        run: |
          docker push ${{ secrets.DOCKER_USERNAME }}/myapp:${{ github.sha }}

Always verify the image exists after building before attempting to push.

### Multi-Stage Build Output

When using multi-stage builds, only the final stage's output is available with the tag you specified. If your Dockerfile has multiple stages, make sure you are not accidentally building an intermediate stage:

dockerfile
# Multi-stage Dockerfile
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/index.js"]
bash
# Build the final stage (default)
docker build -t username/myapp:latest .

# Building a specific stage does NOT create the final image
docker build --target builder -t username/myapp:builder .
# The 'username/myapp:latest' tag does not exist after this command

### Buildx and Multi-Platform Builds

When using Docker Buildx for multi-platform builds, the image may not be loaded locally by default:

bash
# This builds but does NOT load the image locally
docker buildx build --platform linux/amd64,linux/arm64 -t username/myapp .

# To load locally (single platform only)
docker buildx build --load -t username/myapp .

# To push directly without loading locally
docker buildx build --push -t username/myapp .

If you need to push after a buildx build, either use --load or --push flag directly.

### Inspecting Why an Image Is Missing

If you expected an image to exist but cannot find it:

bash
# Check Docker build history
docker history username/myapp:latest 2>/dev/null || echo "Image not found"

# Check for dangling images that might be failed builds
docker images -f "dangling=true"

# Check Docker daemon logs for build errors (Linux)
sudo journalctl -u docker.service --since "1 hour ago" | grep -i error

# Check Docker Desktop logs (macOS/Windows)
# Available through Docker Desktop troubleshooting menu

Frequently asked questions

What does "Error response from daemon: repository does not exist" mean?
This error message appears when the Docker daemon cannot locate a local image matching the repository name you specified in the push command. Unlike authentication errors, this error indicates that Docker never even attempted to contact the registry because it could not find the image to push in the first place. The Docker push command requires an image to exist locally with an exact tag match.
How do I fix "Error response from daemon: repository does not exist"?
The 'repository does not exist' error occurs when Docker cannot find an image locally that matches the tag you are trying to push. This typically happens when the image is not tagged correctly with your Docker Hub username or registry URL, or when the image simply does not exist locally.
What causes "Error response from daemon: repository does not exist"?
Image tagged without Docker Hub username (e.g., 'myimage' instead of 'username/myimage') Typo in the image name, username, or tag when running docker push Image was never built or was built with a different name
Is the "Error response from daemon: repository does not exist" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading