Kubernetes "manifest unknown" - Fix Missing Image Tags in CI

By Daniel Zoghalchali·Latchkey

The registry has the repository but not the specific tag or digest you asked for. "manifest unknown" means that exact reference does not resolve to a stored image.

What this error means

A pull fails with manifest unknown (sometimes manifest for <image> not found). The repository exists, but the tag/digest does not - so the kubelet (or docker) cannot fetch the manifest.

Failed to pull image "myregistry/api:v2.5.0": manifest unknown: manifest unknown

Common causes

The tag was never pushed or was deleted

CI deployed a tag the build never pushed (a race between build and deploy), or a retention policy/garbage collection removed it.

A digest no longer exists

A pinned @sha256:... digest was overwritten or pruned. Mutating a tag (re-pushing :latest) leaves old digests dangling.

No image for the node’s architecture

A single-arch image (amd64) requested on arm64 nodes has no matching manifest in the index, surfacing as manifest unknown for that platform.

How to fix it

Confirm the tag/digest exists in the registry

docker manifest inspect myregistry/api:v2.5.0
# or list available tags via the registry API / UI

Make build-then-deploy ordering correct

1. Ensure the image is fully pushed before the deploy step references it.
2. Deploy by immutable digest captured from the build, not a tag that can drift.
3. For multi-arch, build and push a manifest list covering every node architecture.

How to prevent it

• Deploy the exact digest the build produced, not a re-tagged reference.
• Sequence pipelines so push completes before deploy.
• Publish multi-arch manifest lists when nodes span architectures.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation