docker manifest unknown: 4 Reasons the Tag Can't Be Found

Symptom: the repo exists, the tag doesn't

Error response from daemon: manifest for myapp/api:v1.2.0 not found:
manifest unknown: manifest unknown

One-line diagnosis: the registry knows the repository, but can't find a manifest for the tag you wrote. A manifest is the image's table of contents (listing layers per architecture) and a tag points to one — wrong tag, or pointing at nothing, produces this error.

It's the sibling of pull access denied: denied is a repository-level problem (missing/no permission), manifest unknown is a tag-level problem inside the repo. Seeing manifest unknown usually means the repo name is right — focus on the tag.

Four causes, ranked by frequency

1. Tag typo (most common)

Case-sensitive, v1.2 and 1.2 are different tags, and -/_ look alike. The reliable check — ask the registry directly:

# List an image's tags (Docker Hub)
curl -s "https://hub.docker.com/v2/repositories/library/nginx/tags?page_size=20" | grep -o '"name":"[^"]*"'

# Or verify a specific manifest exists
docker manifest inspect myapp/api:v1.2.0

2. The latest trap: the image has no latest tag

docker pull myapp/api with no tag defaults to latest. Official images maintain it, but personal/team images frequently only pushed version tags — docker push myapp/api:v1.2.0 does not create latest. Spell the tag out:

docker pull myapp/api:v1.2.0   # ✅ explicit tag
docker pull myapp/api          # ❌ pulls a latest that may not exist

3. The official image was renamed or retired

The ecosystem moves: repositories transfer (old ones archived read-only), get renamed, or prune version tags. If your Dockerfile/docs are a few years old, verify with docker manifest inspect, then search Hub for the new home.

4. Architecture mismatch: the manifest exists, but not for your platform

With docker pull --platform linux/amd64 myapp/api:v1, if that tag was only ever pushed for arm64, you get manifest unknown or no matching manifest. Frequent for cross-builds from M-series Macs:

# Which platforms does this tag have?
docker manifest inspect myapp/api:v1 | grep -A2 platform

# Build explicitly for the target platform
docker buildx build --platform linux/amd64 -t myapp/api:v1 --push .

exec format error at runtime is what happens when this mismatch slips past the pull stage — align platforms at pull time.

The triage flow (two minutes, in order)

# 1. List the tags that actually exist
curl -s "https://hub.docker.com/v2/repositories/<user>/<repo>/tags?page_size=50" | grep -o '"name":"[^"]*"'

# 2. Tag looks right but still failing? Check manifest and architecture
docker manifest inspect <full-image-name:tag>

# 3. Pulled without a tag? Add the explicit tag and retry
docker pull <full-image-name>:<explicit-tag>

Telling the neighboring errors apart

| Error | Level | Direction | |---|---|---| | manifest unknown / not found | tag level | this post | | pull access denied | repository level | pull access denied | | no matching manifest for platform | architecture level | cause 4 here | | exec format error | runtime architecture | align platforms at pull time |

Checklist

1. Character-by-character tag check (case, v prefix, separators)
2. No tag written = pulling latest — does this image really have one?
3. Hub Tags page / registry API for the real tag list
4. Using --platform? Confirm the tag has a manifest for it
5. Old Dockerfile image names: verify the repo wasn't renamed or retired

Provided by ToolVault. Related tools: Dockerfile Generator, Linux Cheatsheet. Related reading: pull access denied, Docker disk cleanup. See the homepage for more developer tools.