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.
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
First, check what images exist locally and confirm the exact name and tag:
# List all local images
docker images
# Search for a specific image
docker images | grep myimage
# Show full image details including digests
docker images --no-truncLook 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.
If the image exists but without your username, tag it correctly:
# 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:latestReplace 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.
If the image is not in your local Docker images list, you need to build it:
# 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/myimageBuilding with the correct tag from the start avoids the need for a separate tagging step.
Carefully compare the image name in your push command with the actual local image:
# 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.
If pushing to a private registry (not Docker Hub), include the full registry URL in the tag:
# 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:latestThe tag must exactly match the registry URL you are pushing to.
When using Docker Compose, ensure the image name in your compose file matches what you are trying to push:
# docker-compose.yml
services:
myapp:
build: .
image: YOUR_DOCKERHUB_USERNAME/myapp:latestThen build and push:
# Build with compose
docker compose build
# Push with compose
docker compose push
# Or push the specific image
docker push YOUR_DOCKERHUB_USERNAME/myapp:latestIf 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.
### Understanding Docker Image Naming
Docker image names follow a specific format:
[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:
# 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:
# 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"]# 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:
# 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:
# 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 menuimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub