How to fix manifest unknown in Kubernetes

KubernetesBEGINNERMEDIUMUpdated Dec 5, 2025· 238 views

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.

Quick fix

Fixes manifest unknown

# 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
  1. Verify the image name and tag exist
  2. Use crane to inspect without pulling
  3. Use skopeo for deep registry inspection
  4. Check for typos in image reference
kubernetes — error
# 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
manifest unknown

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".

Typical symptoms

  • Docker pull fails immediately with "manifest unknown: manifest unknown"
  • Kubernetes pod enters ImagePullBackOff with manifest error in events
  • Works for one tag (v1.0) but fails for another (v2.0)
  • Image existed previously but now fails to pull
  • Works locally after docker login but fails in CI/CD or Kubernetes

Common causes

  1. Incorrect or misspelled image name/tag (ubuntu:20.4 instead of ubuntu:20.04)
  2. Image or tag was deleted from the registry
  3. Using deprecated image path (old Docker Hub location)
  4. Authentication required but credentials missing (registry reports not found instead of unauthorized)
  5. Architecture mismatch—manifest list exists but not for your platform

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 .

Advanced notes

Multi-Architecture Manifest Lists: A "manifest list" points to multiple platform-specific manifests. When you pull ubuntu:22.04, Docker fetches the manifest list, finds your platform (amd64/arm64), and downloads that specific variant. If your platform isn't in the list, you get "manifest unknown".

Schema Version Mismatches: Docker V2 Schema 1 (legacy) vs Schema 2 (current). Most registries default to Schema 2. Missing Accept headers can cause fallback issues—update Docker to latest.

Deprecated Registries: GitHub's old docker.pkg.github.com is deprecated; migrate to ghcr.io. Jenkins moved from jenkins:latest to jenkins/jenkins:lts.

Registry-Specific Issues:
- Docker Hub: Verify tag exists in web UI
- ACR: Check az acr repository show-tags
- GCR: Verify IAM permissions include artifactregistry.repositories.downloadArtifacts
- JFrog: Use full path including /artifactory/api/docker/

Frequently asked questions

What does "manifest unknown" mean?
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.
How do I fix "manifest unknown"?
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 causes "manifest unknown"?
Incorrect or misspelled image name/tag (ubuntu:20.4 instead of ubuntu:20.04) Image or tag was deleted from the registry Using deprecated image path (old Docker Hub location)
Is the "manifest unknown" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading