Docker Compose "pull ... manifest unknown / not found" - Fix Image References

By Kaveh Alemi·Latchkey

Compose tried to pull a service’s image: and the registry has no such tag. The repository may exist, but the exact tag referenced in the compose file was never published.

What this error means

A docker compose pull or up fails for one service with manifest unknown / not found for its image. Other services pull fine; only this service’s tag is missing from the registry.

Error response from daemon: manifest for myorg/api:relese-1 not found:
manifest unknown: manifest unknown
# service "api" in docker-compose.yml references image: myorg/api:relese-1

Common causes

The image tag does not exist

A misspelled tag (relese-1), or a tag a prior job was supposed to push but did not, leaves nothing for Compose to pull.

A build-only service is being pulled

A service that should be built locally (only build:) but also has a stale image: tag can trigger a pull of an image that was never pushed.

Wrong registry/namespace in the image reference

An image: value pointing at the wrong registry or namespace resolves to a repository/tag that does not contain the image.

How to fix it

Reference an image tag that exists, or build it

Fix the tag, or build the service instead of pulling it.

# build locally instead of pulling a non-existent tag:
docker compose build api && docker compose up -d
# or correct the image tag in the compose file

Verify the tag in the registry

Inspect the referenced image before relying on it.

docker buildx imagetools inspect myorg/api:1.4.2
# confirm the exact tag from the compose file exists

How to prevent it

• Ensure the image tag is pushed before a downstream compose job pulls it.
• Pin compose image: tags to ones that actually exist (or digests).
• For build-only services, avoid a stale image: that triggers an errant pull.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation