How to fix manifest unknown in Kubernetes

KubernetesBEGINNERMEDIUM

This error occurs when the container registry cannot find the manifest for the requested image tag. Fix it by verifying the image name and tag exist in the registry, checking for typos, and ensuring proper authentication.

What this error means

The "manifest unknown" error indicates that Docker or Kubernetes requested an image manifest from a container registry, but the registry has no manifest matching that reference. A manifest is the metadata file containing information about image layers, configuration, and tags—without it, the image cannot be pulled. This typically happens when you reference an image tag that doesn't exist, has been deleted, or contains a typo. The registry receives the request but cannot locate any manifest data for that specific image:tag combination. Common scenarios include misspelled tags (ubuntu:20.4 instead of 20.04), deleted images, deprecated repositories (jenkins:latest moved to jenkins/jenkins:lts), or authentication issues causing the registry to report "not found" instead of "unauthorized".

How to fix "manifest unknown"

1Verify the image name and tag exist

Check if the exact image:tag combination exists:

bash

# Try pulling directly to see detailed error
docker pull ubuntu:22.04

# Use crane to verify without downloading
crane manifest docker.io/library/ubuntu:22.04 || echo "Tag does not exist"

# Check digest exists
crane digest ubuntu:22.04

For Docker Hub images, verify on hub.docker.com by browsing to the repository's Tags tab.

2Use crane to inspect without pulling

Install and use crane for lightweight manifest inspection:

bash

# Install crane (macOS)
brew install crane

# Verify image exists and get digest
crane digest ubuntu:22.04
# Output: sha256:1a...abc

# Inspect full manifest structure
crane manifest ubuntu:22.04

# For private registries with authentication
crane auth login myregistry.azurecr.io -u username -p password
crane manifest myregistry.azurecr.io/myimage:v1.0

Crane checks existence without downloading the full image.

3Use skopeo for deep registry inspection

Skopeo provides detailed registry inspection:

bash

# Install skopeo (Linux)
sudo apt-get install skopeo

# Inspect remote image
skopeo inspect docker://ubuntu:22.04

# For private registries
skopeo inspect --creds username:password \
  docker://myregistry.azurecr.io/myimage:v1.0

# Check available architectures in manifest list
skopeo inspect --raw docker://ubuntu:22.04 | jq '.manifests[].platform'

Skopeo doesn't require a Docker daemon and shows full multi-arch manifest details.

4Check for typos in image reference

Common typos and corrections:

bash

# Wrong
docker pull ubunt:22.04      # Misspelled 'ubuntu'
docker pull ubuntu:22.4      # Missing zero in version
docker pull nginx:latst      # Misspelled 'latest'

# Correct
docker pull ubuntu:22.04
docker pull nginx:latest

Full image reference format: registry/namespace/image:tag

Examples:
- Docker Hub official: ubuntu:22.04 or docker.io/library/ubuntu:22.04
- Docker Hub user: myuser/myapp:v1.0
- Private registry: myregistry.azurecr.io/myapp:latest

5Authenticate to private registries

Some registries return "manifest unknown" instead of "unauthorized":

bash

# Docker Hub
docker login
# Use personal access token, not password

# Azure Container Registry
az acr login --name myregistry

# GitHub Container Registry (use ghcr.io, not docker.pkg.github.com)
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Google Container Registry
gcloud auth configure-docker

Verify authentication:

bash

cat ~/.docker/config.json | jq '.auths'

6Clear cache and retry

If manifest was recently updated or you suspect cache issues:

bash

# Remove local Docker cache
docker system prune -a

# Force fresh pull (no cache)
docker pull --disable-content-trust ubuntu:22.04

# For buildx multi-arch, disable attestations if causing issues
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --provenance false \
  --sbom false \
  -t myimage:v1.0 .

How to fix manifest unknown in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "manifest unknown"

Advanced notes

Related errors

Official resources & further reading