Containers & Kubernetes / Incident Response & Troubleshooting

Fix Docker failed to resolve reference and manifest unknown

Diagnose Docker failed to resolve reference and manifest unknown errors by proving the exact image name, registry path, authentication boundary, tag or digest, daemon network path, and target platform before retrying a pull or deployment.

35 min12 stepsChanges system stateRevision 1

Save or explore

#docker #registry #manifest-unknown #image-pull #buildx #multi-platform

0 of 12 steps completed

Goal

Resolve a Docker image reference without weakening registry authentication, bypassing TLS, guessing a mutable tag, or deploying an image for the wrong architecture.

Supported environments

Docker Engine 25.x, 26.x, 27.x, 28.x, 29.x
Docker Desktop 4.x
Docker Buildx 0.17+

Prerequisites

Exact failed reference Copy the image reference exactly as the failing client, Compose file, CI job, or deployment produced it.The record includes registry host, repository path, tag or digest, and requested platform when one was set.
Registry access boundary Know whether the repository is public or private and which approved identity is expected to read it.An owner can confirm the repository path and the expected read permission without sharing a token.
Safe comparison Keep one known-good image reference from the same registry or an independently verified digest for comparison.The reference is immutable or its current digest is recorded before troubleshooting.
Change and recovery path Identify the deployment owner and retain the last known-good image digest before changing a production reference.The previous digest or release definition can be restored without relying on the failing tag.

Operating boundary

OneLiners never runs these steps or stores secrets. Review placeholders, versions, current state, and change-control requirements before using a command.

Full guide

What you will build

System

A repeatable decision path for Docker failed to resolve reference and manifest unknown that starts with the exact image value and ends with an approved immutable digest.
A layered evidence bundle covering client and daemon context, registry DNS and TLS, token exchange, repository authorization, manifest existence, platform compatibility, layer download, and the real deployment source.
A safe recovery plan that keeps the last known-good image available and refuses shortcuts such as public repositories, administrator tokens, insecure registries, unverified local retagging, or architecture forcing.

Observable outcome

You can tell whether the failure belongs to name construction, artifact publication, authorization, daemon networking, or platform selection before changing anything.
The original pull, build, Compose, CI, or deployment path succeeds with the intended identity and exact digest, while an unauthorized control remains denied.
Future releases record and preflight immutable digests, expected platforms, and repository permissions so a missing manifest is detected before production rollout.

Architecture

How the parts fit together

Docker image resolution crosses several independent boundaries. The client supplies a reference to a selected daemon or BuildKit builder; that runtime resolves the registry host, negotiates TLS and any proxy, obtains a scoped token, requests a repository manifest, selects a compatible platform descriptor, and downloads its blobs. A short manifest unknown message can therefore describe an absent tag, a hidden private repository, or a wrong path, while failed to resolve reference can also include transport and token failures. The guide changes one layer at a time and preserves the immutable digest as the decision anchor.

Reference producerCompose, CI, a Dockerfile, environment expansion, or deployment code that renders registry, repository, tag, digest, and optional platform.

Docker client and contextSelects the daemon or builder endpoint and the credential configuration used for the request.

Registry transportResolves DNS, validates TLS, applies daemon or Desktop proxy policy, and exposes the registry v2 API.

Token and repository authorizationAuthenticates the workload identity and grants the narrow pull scope for one repository.

Manifest and platform indexMaps a tag or digest to immutable metadata and selects an OS and architecture variant.

Release and deployment controlPublishes approved artifacts, records their digests, renders the production reference, verifies rollout, and preserves rollback.

The release or deployment source renders a complete image reference and sends it to the selected Docker daemon or BuildKit builder.
The runtime resolves the registry hostname, validates the HTTPS certificate, and reaches the registry /v2/ endpoint through its own proxy and DNS boundary.
The registry token service authenticates the identity and issues repository-scoped pull authorization.
The registry resolves the tag or digest to a manifest or multi-platform image index. A private registry may hide unauthorized repositories with a not-found response.
Docker selects the descriptor matching the requested platform and downloads the referenced layers.
The deployment records the immutable RepoDigest or runtime imageID, runs health checks, and retains the prior digest until the observation window closes.

Assumptions

The operator can reproduce the exact failing reference in the same Docker context, builder, runner, or workload boundary.
The registry owner or release system can confirm whether a tag or digest exists without exposing a credential or proprietary layer.
The organization has an approved method for short-lived pull credentials and does not require passwords in command arguments.
A last known-good immutable image digest, deployment revision, or signed release record exists before production reference changes.
DNS, TLS, proxy, registry authorization, image publication, and platform selection are owned separately enough that evidence can be escalated to the correct team.
OneLiners never runs these commands or stores registry credentials; every placeholder, context, target, and release value must be reviewed locally.

Key concepts

Image reference: A registry host and repository path followed by an optional mutable :tag or immutable @sha256:digest. Omitting parts changes Docker's default resolution behavior.
Manifest: Immutable registry metadata that identifies the image configuration and layer digests for one platform.
Image index: A manifest list that points to several platform-specific manifests, such as linux/amd64 and linux/arm64.
manifest unknown: A registry response stating that the requested manifest name is unavailable to the caller. It can mean an absent tag or digest, a wrong repository path, or deliberately hidden private content.
failed to resolve reference: A Docker or BuildKit resolution failure before a usable image manifest is selected; transport, token, repository, manifest, and platform failures can all appear in this family.
RepoDigest: The immutable repository-qualified digest recorded after a pull, suitable for provenance comparison and production pinning.
Docker context: The selected client endpoint and metadata that determine which daemon receives a command.
Platform descriptor: The operating system, CPU architecture, and optional variant attached to a manifest in a multi-platform index.

Set guide values0/6 ready

Fill these once. Every matching command and configuration block updates immediately; values stay in this page only.

Image Ref{{imageRef}}Complete failing or corrected image reference, including registry and tag or digest.Registry Host{{registryHost}}Registry hostname, including a non-default port when required.Repository Path{{repositoryPath}}Repository namespace and name inside the registry.Tag Name{{tagName}}Requested release tag as rendered by the deployment source.Platform Name{{platformName}}Required Docker platform in OS/architecture form.Known Good Ref{{knownGoodRef}}Independently verified immutable reference in the same registry path.

Security and production boundaries

Use repository-scoped pull credentials and standard input or an approved credential helper. Never place tokens in URLs, shell history, process arguments, screenshots, or Guide fields.
A registry can intentionally return not found for private content. Do not infer that a repository is absent until the expected identity and scope are proven.
Do not disable TLS verification, configure an insecure registry, trust an unknown CA, or bypass the corporate proxy merely to convert the error into a successful pull.
Do not make a private repository public or grant registry-wide read access. A successful negative control is part of the repair evidence.
Do not retag and push an arbitrary local image to satisfy a missing production tag. Artifact provenance, signing, SBOM, scanning, and release approval still apply.
Record immutable digests and platform descriptors but redact signed blob URLs, token realms with sensitive query parameters, internal tenant paths, and private registry topology.

Stop before continuing if

Stop if the exact failed reference, Docker context, requested platform, and last known-good digest are not recorded.
Stop when DNS, certificate identity, redirects, or proxy routing point to an unexpected registry boundary.
Stop if the only available credential has write, delete, owner, or registry-administrator permissions for a read diagnosis.
Stop before creating or moving a tag when the proposed image digest lacks the required provenance and release approval.
Stop if the requested platform is not present and emulation or node rescheduling has not been reviewed.
Stop before deploying when the pulled digest differs from signed or independently approved release evidence.
Stop if a manual shell succeeds but the original CI, Compose, or orchestrator path still renders another reference or identity.

instruction

Preserve the literal failure and its execution context

read-only

Start with the first Docker failed to resolve reference or manifest unknown response. Record whether it came from docker pull, Docker Compose, BuildKit, a CI runner, or an orchestrator. Preserve the complete image reference and the selected platform; do not shorten the name or replace the tag while collecting evidence.

Why this step matters

Image-resolution messages are intentionally compact and several independent failures can look similar. The untouched reference and context separate an absent manifest from wrong credentials, a different daemon, or a platform-selection failure.

What to understand

Record the source file and line that supplied the reference, such as an IMAGE variable, Compose service, Kubernetes workload, Dockerfile FROM instruction, or CI release job. A working interactive pull does not disprove a different automated value.

Preserve the earliest registry response. Repeated retries can replace a clear manifest unknown response with rate limiting, cached credentials, proxy errors, or a partially changed deployment.

Capture the exact command, UTC timestamp, exit status, selected Docker context, and unredacted structural fields before moving to the next layer. Redact credentials and private payloads, but preserve registry, repository, tag, digest, platform, and response status.

Treat one matching line as evidence for a hypothesis, not permission to change authentication, proxy, DNS, or image policy globally. Compare the result with a known-good host or reference only when the comparison uses the same registry path.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Example output / evidence

$ docker pull registry.example.com/team/api:2026.08.23
Error response from daemon: failed to resolve reference registry.example.com/team/api:2026.08.23: registry.example.com/team/api:2026.08.23: not found: manifest unknown
Exit status: 1
Observed at: 2026-08-23T18:22:14Z
Docker context: production-builder
Requested platform: linux/amd64

Security notes

Do not paste registry passwords, bearer tokens, authorization headers, complete Docker config files, or private image layer URLs into the incident record.

Alternatives

If production output is restricted, reproduce the exact reference and platform from a host with equivalent Docker and registry policy, and label the evidence as a comparison rather than production proof.

Stop conditions

Stop before editing the image reference when the failed value, selected Docker context, requested platform, or last known-good digest has not been recorded.

command

Resolve the registry, repository, tag, and digest literally

read-only

Print the supplied values separately and check for invisible whitespace, a missing registry namespace, an implicit latest tag, or a digest that was combined incorrectly with a tag. Docker image names use registry host, repository path, and an optional tag or digest; a short name can resolve to Docker Hub rather than the intended private registry.

Why this step matters

Most registry investigations become misleading when people discuss a friendly image name while the daemon received a different fully qualified reference.

What to understand

A reference without a registry host normally uses Docker Hub; a repository without the intended organization can point at library or another namespace. A reference without a tag uses latest, which may not exist even when other tags do.

A digest reference uses the form repository@sha256:value and is immutable. Do not append a tag after the digest or assume a digest from a different repository is interchangeable.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

registry host: Selects the network and trust boundary that stores the repository.
repository path: Selects the namespace and image repository inside that registry.
:tag: Selects a mutable name that must currently map to a manifest.
@sha256:digest: Selects one immutable manifest by content digest.

Command

Fill variables0/4 ready

Values stay on this page and are never sent or saved.

Registry Host{{registryHost}}Registry hostname, including a non-default port when required.Repository Path{{repositoryPath}}Repository namespace and name inside the registry.Tag Name{{tagName}}Requested release tag as rendered by the deployment source.Image Ref{{imageRef}}Complete failing or corrected image reference, including registry and tag or digest.

printf 'registry=%s\nrepository=%s\ntag=%s\nreference=%s\n' '{{registryHost}}' '{{repositoryPath}}' '{{tagName}}' '{{imageRef}}'

Example output / evidence

registry=registry.example.com
repository=team/api
tag=2026.08.23
reference=registry.example.com/team/api:2026.08.23

Checkpoint: Checkpoint: the failed reference is unambiguous

printf '%s\n' '{{imageRef}}'

Continue whenOne fully qualified reference is recorded with no whitespace, shell expansion, or implicit namespace.

Stop whenThe value differs between the deployment definition, environment, and actual Docker command.

If this step fails

The command tries docker.io although a private registry was expected.

Likely causeThe registry hostname was omitted or an environment variable expanded to an empty value.

Safe checks

Inspect the rendered Compose or CI configuration without printing secrets.
Compare the literal reference with {{imageRef}}.

ResolutionCorrect the versioned deployment source so it emits the fully qualified private-registry reference; do not repair only an interactive shell.

Security notes

Treat private repository names as operational metadata and redact tenant-specific segments when evidence leaves the team.

Alternatives

Use a digest-pinned known-good reference when release policy already records immutable digests.

Stop conditions

Stop if the value is dynamically assembled and the exact rendered reference cannot be reproduced.

command

Confirm the Docker client, daemon, and selected context

read-only

Verify that the failing client talks to the intended Docker daemon. Docker Desktop, remote contexts, rootless daemons, buildx builders, and CI runners can use different credentials, DNS, proxy settings, and image stores even on the same workstation.

Why this step matters

A successful test against a local daemon is irrelevant when the failed build or pull ran through a remote builder or another Docker context.

What to understand

Match client and server versions, endpoint, and context name to the original output. In CI, run the check inside the same job and container that performs the pull.

For buildx failures, also record the selected builder because BuildKit may fetch base images from a different network namespace and credential boundary than docker pull.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

docker version: Shows both client and reachable daemon versions; a missing Server section indicates the daemon path failed first.
docker context show: Prints the context actually selected for this command.
docker context inspect: Shows the endpoint without changing the selected context.

Command

docker version && docker context show && docker context inspect $(docker context show)

Example output / evidence

Client: Docker Engine - Community
 Version: 28.3.2
Server: Docker Engine - Community
 Engine:
  Version: 28.3.2
production-builder
[{"Name":"production-builder","Endpoints":{"docker":{"Host":"ssh://builder.example.com"}}}]

Checkpoint: Checkpoint: the failing daemon is identified

docker context show && docker version

Continue whenThe selected endpoint and daemon version match the environment that reported the error.

Stop whenThe command reaches a different daemon, builder, or operating mode than the failed workload.

If this step fails

Client information appears but Server information is absent.

Likely causeThe Docker daemon or selected context is unreachable, so registry diagnosis has not begun.

Safe checks

docker context show
docker context inspect $(docker context show)

ResolutionRepair the daemon or context path first, then reproduce the original image request without changing it.

Security notes

Context inspection can expose internal hostnames. Preserve the endpoint for operators but remove it from public screenshots.

Alternatives

On Docker Desktop, record the active Linux or Windows container mode and use Desktop diagnostics for the selected engine.

Stop conditions

Stop registry changes if the Docker client is not connected to the daemon that produced the failure.

command

Check DNS, TLS, and the daemon proxy path to the registry

read-only

Resolve the registry host and inspect its HTTPS endpoint before changing credentials. Docker pulls are performed by the daemon or builder, so a shell-level proxy test may differ from the actual fetch path. A registry often returns HTTP 401 at /v2/ when it is reachable but requires authentication; that is useful transport evidence.

Why this step matters

Authentication and manifest checks are unreliable until the selected host resolves, presents the expected certificate, and exposes a registry API response through the actual network boundary.

What to understand

A 401 response with Docker distribution headers proves DNS, TCP, TLS, and the registry front door are available; it does not prove the repository exists or that the Docker identity can read it.

If Docker uses a daemon proxy, inspect the effective daemon or Desktop setting rather than exporting shell variables blindly. NO_PROXY must include an internal registry when policy requires direct access.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

nslookup: Resolves the registry hostname using the host resolver without changing DNS configuration.
--head: Requests headers only; the registry may reject HEAD, so compare with a bounded GET if policy allows.
--connect-timeout 5: Bounds the connection attempt so a broken route does not stall the evidence step.
/v2/: Targets the standard registry API base endpoint rather than a marketing or management page.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Registry Host{{registryHost}}Registry hostname, including a non-default port when required.

nslookup {{registryHost}} && curl --fail-with-body --silent --show-error --head --connect-timeout 5 https://{{registryHost}}/v2/

Example output / evidence

Name: registry.example.com
Address: 203.0.113.24
HTTP/2 401
docker-distribution-api-version: registry/2.0
www-authenticate: Bearer realm="https://registry.example.com/token",service="registry.example.com"

Checkpoint: Checkpoint: the registry transport boundary responds

curl --silent --show-error --head --connect-timeout 5 https://{{registryHost}}/v2/

Continue whenThe expected registry returns a TLS-valid 200 or authentication challenge with registry headers.

Stop whenDNS selects an unexpected address, the certificate identity is wrong, an interception page appears, or the proxy path is unknown.

If this step fails

curl succeeds from the shell but docker pull times out.

Likely causeThe daemon or BuildKit builder uses different proxy, DNS, CA, or network-namespace settings.

Safe checks

docker info
Inspect approved daemon or Docker Desktop proxy settings.
Run the same pull from the original builder context.

ResolutionCorrect the daemon or builder network configuration through the supported configuration path; do not disable TLS verification.

The endpoint returns an HTML login page.

Likely causeA reverse proxy, captive portal, or SSO front end intercepted the registry API path.

Safe checks

curl --head https://{{registryHost}}/v2/
Compare certificate subject and response headers with the registry owner.

ResolutionRoute the registry API path to the registry service and keep human SSO outside the Docker token exchange.

Security notes

Never add an insecure-registry setting or disable certificate verification merely to make this step pass.

Alternatives

Use Docker Desktop's supported proxy settings on Desktop because daemon.json proxy keys do not control that product.

Stop conditions

Stop if the certificate, DNS answer, redirect target, or proxy destination does not belong to the intended registry.

command

Test the approved registry identity without exposing credentials

caution

Authenticate to the intended registry using a short-lived, least-privilege credential provided through standard input. Do not place a password or token in command history. A successful login proves token exchange, not repository authorization; continue to the manifest check.

Why this step matters

Registry authentication failures can be reported as pull access denied or hidden behind a generic not-found response, especially when a registry avoids revealing private repository names.

What to understand

Use a robot, workload, or personal token with read-only package scope. Confirm the credential is intended for the exact registry host and has not expired.

Docker stores credentials using the configured credential store or Docker config. On shared or ephemeral hosts, use an isolated DOCKER_CONFIG and remove it after the test according to local policy.

System changes

Updates the selected Docker credential store or temporary DOCKER_CONFIG with an authentication entry for {{registryHost}}.

Syntax explained

--password-stdin: Reads the secret from standard input instead of exposing it in arguments or shell history.
--username: Identifies the registry account paired with the token; some registries require a fixed robot username.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Registry Host{{registryHost}}Registry hostname, including a non-default port when required.

printf '%s' "$REGISTRY_TOKEN" | docker login {{registryHost}} --username "$REGISTRY_USER" --password-stdin

Example output / evidence

Login Succeeded

Checkpoint: Checkpoint: token exchange succeeds for the intended host

docker login {{registryHost}} --username "$REGISTRY_USER" --password-stdin

Continue whenDocker reports Login Succeeded and no secret appears in process arguments or captured output.

Stop whenThe token has write or administrative scope, belongs to another host, or would be stored on an untrusted shared runner.

If this step fails

Likely causeThe identity lacks repository read permission, the repository path is wrong, or the requested tag or digest does not exist.

Safe checks

Ask the registry owner to confirm read permission for {{repositoryPath}}.
Inspect {{imageRef}} with the same Docker context.

ResolutionGrant only the required read permission or correct the versioned repository path; do not broaden access to the whole registry.

The registry rejects the token as unauthorized.

Likely causeWrong host, expired credential, incorrect username convention, missing scope, or clock skew in a token exchange.

Safe checks

Confirm the credential audience and expiration without printing it.
Compare system time with the organization's approved time source.

ResolutionIssue or select a fresh read-only credential for the exact registry and repository.

Security notes

Never paste REGISTRY_TOKEN into the guide, an incident comment, command history, or a URL. Revoke temporary credentials after the observation window.

Alternatives

Use the registry's approved cloud or workload-identity helper when static tokens are prohibited.

Stop conditions

Stop if only a write-capable or administrator credential is available for a read-only diagnosis.

command

Prove whether the tag or digest exists

read-only

Inspect the remote image metadata without pulling layers. Run the check with the same authenticated Docker context and exact reference. A returned index or manifest proves that the registry can resolve the name for this identity; manifest unknown proves that the selected repository, tag, or digest is absent or deliberately hidden by authorization policy.

Why this step matters

Remote manifest inspection distinguishes an absent name from a layer-download failure and exposes the immutable digest plus published platform variants.

What to understand

If the exact digest resolves but the tag does not, the tag was not published, was removed, or points in another repository. If the tag resolves to an unexpected digest, stop and investigate release provenance rather than pulling it.

Some registries hide private repository existence from unauthorized clients by returning not found or manifest unknown. Repeat the check only after the approved identity is proven.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

docker buildx imagetools inspect: Reads an image manifest or index from the registry without downloading image filesystem layers.
{{imageRef}}: Uses the complete registry, repository, tag or digest captured from the failed operation.

Uses verified command record: devops-registry-image-inspect

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Image Ref{{imageRef}}Complete failing or corrected image reference, including registry and tag or digest.

docker buildx imagetools inspect {{imageRef}}

Example output / evidence

Name:      registry.example.com/team/api:2026.08.23
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:4c4b0f4db44c8b88b7f00ecf269aaf6ba5cb6fd917cd92068f7da57d06d5608f
Manifests:
  Name: registry.example.com/team/api@sha256:8c61...
  Platform: linux/amd64
  Name: registry.example.com/team/api@sha256:72e4...
  Platform: linux/arm64

Checkpoint: Checkpoint: registry name resolution is proven

docker buildx imagetools inspect {{imageRef}}

Continue whenThe registry returns one manifest or index, its immutable digest, and any published platform variants.

Stop whenThe digest differs from release evidence, the repository owner cannot confirm the tag, or authorization remains ambiguous.

If this step fails

failed to resolve reference ... manifest unknown

Likely causeThe exact tag or digest is absent in this repository, or the registry hides it from this identity.

Safe checks

docker buildx imagetools inspect {{knownGoodRef}}
Ask the repository owner to confirm {{tagName}} and its digest from registry audit data.

ResolutionCorrect the source release reference or publish the missing artifact through the approved pipeline; do not create a replacement tag from an unverified local image.

failed to authorize: failed to fetch anonymous token

Likely causeThe client attempted anonymous access or token service scope did not match the repository.

Safe checks

docker context show
docker login {{registryHost}} with a read-only token

ResolutionRepair the approved authentication path and repeat the same manifest inspection.

Security notes

Manifest metadata can reveal private repository names, release cadence, and architecture; share it only inside the incident boundary.

Alternatives

Use docker manifest inspect {{imageRef}} when Buildx is unavailable, noting that docker manifest remains experimental in some CLI versions.

Stop conditions

Stop before publishing or retagging when the expected digest is not independently recorded.

decision

Separate a missing artifact from a registry-wide failure

read-only

Inspect one approved known-good reference in the same repository and through the same context. If it resolves, DNS, TLS, token exchange, and basic repository read permission are working; focus on the missing tag or digest. If both fail, return to transport and authorization evidence instead of creating tags.

Why this step matters

A controlled reference from the same namespace tests the registry path while changing only the artifact selector.

What to understand

Choose a known-good digest from signed release metadata, a running workload, or a registry audit record. Do not use latest as the control because it can move or be absent by policy.

A working public image from another registry is not a valid control for private DNS, certificate, token service, repository scope, or proxy exceptions.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

{{knownGoodRef}}: An independently verified immutable digest in the same registry and preferably the same repository.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Known Good Ref{{knownGoodRef}}Independently verified immutable reference in the same registry path.

docker buildx imagetools inspect {{knownGoodRef}}

Example output / evidence

Name:      registry.example.com/team/api@sha256:90c0...
MediaType: application/vnd.oci.image.manifest.v1+json
Digest:    sha256:90c0c858b12ab9f272cb2be60770dd22685a9353ebcd6ff4c018f9ee6a1d3f9e

Checkpoint: Checkpoint: the failure boundary is isolated

docker buildx imagetools inspect {{knownGoodRef}}

Continue whenThe comparison either resolves with its recorded digest or fails at the same transport or authorization layer as the target.

Stop whenThe control is mutable, belongs to another registry path, or lacks independent provenance.

If this step fails

The known-good digest also fails.

Likely causeThe problem is broader than the requested tag: context, DNS, TLS, proxy, authentication, or repository permission.

Safe checks

Repeat the registry /v2/ transport check.
Confirm docker context show and registry login for {{registryHost}}.

ResolutionReturn to the first failing boundary and repair it before changing image metadata.

Security notes

Do not grant repository-wide access simply to create a comparison; use an existing artifact already authorized for the workload.

Alternatives

Compare against the exact digest already running in production when registry policy allows it to be inspected.

Stop conditions

Stop if the known-good reference is not demonstrably immutable and trusted.

command

Match the requested operating system and architecture

read-only

Compare the daemon platform with every platform advertised by the image index. A tag can exist and still fail with no matching manifest when the registry index lacks linux/amd64, linux/arm64, windows/amd64, or the requested variant.

Why this step matters

Platform mismatch is an artifact-publication problem, not a reason to force an incompatible image or change authentication.

What to understand

Docker normally selects the compatible manifest from an image index. An explicit --platform setting in Compose, buildx, or CI can override the daemon default and request a variant that does not exist.

Windows container images also depend on operating-system compatibility beyond the architecture label. Confirm the supported host and container versions in the image owner's release policy.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

docker version: Reports the selected daemon operating system and architecture boundary.
imagetools inspect: Lists the platform descriptors actually published under the image reference.
--platform: Requests a specific OS and architecture; it must correspond to a published manifest.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Image Ref{{imageRef}}Complete failing or corrected image reference, including registry and tag or digest.

docker version && docker buildx imagetools inspect {{imageRef}}

Example output / evidence

Server:
 OS/Arch: linux/arm64

Name: registry.example.com/team/api:2026.08.23
Manifests:
  Platform: linux/amd64

Decision: requested linux/arm64 is not published

Checkpoint: Checkpoint: a compatible manifest exists

docker buildx imagetools inspect {{imageRef}}

Continue whenThe index includes {{platformName}}, or the release owner confirms that the reference is intentionally single-platform.

Stop whenThe requested platform is absent, emulation policy is unclear, or the returned digest is not the approved release.

If this step fails

no matching manifest for linux/arm64/v8 in the manifest list entries

Likely causeThe tag exists but its index contains no arm64 variant.

Safe checks

docker buildx imagetools inspect {{imageRef}}
Confirm the CI build platform matrix.

ResolutionPublish a tested arm64 manifest through the release pipeline or select a documented compatible release; do not relabel an amd64 manifest as arm64.

Security notes

Emulation changes performance and attack-surface assumptions; use it only when explicitly supported and tested.

Alternatives

Run the workload on a compatible node only when scheduling and capacity policy explicitly supports that choice.

Stop conditions

Stop before forcing a platform that the artifact owner does not test or support.

instruction

Repair the release source, not only the interactive command

caution

Choose the narrow repair supported by evidence: correct a misspelled registry or repository, select an existing tag, pin the approved digest, restore repository read scope, repair daemon network configuration, or publish the missing platform variant. Make the change in the versioned Compose, CI, deployment, or image-build source that produced the bad reference.

Why this step matters

An interactive docker pull can look fixed while CI, Compose, or the orchestrator continues to emit the original invalid value.

What to understand

Prefer an immutable digest for production deployment and retain the human-readable tag in release metadata. If policy uses tags, record the resolved digest at promotion time and prevent later movement.

When the artifact truly was not published, rerun the approved build and publish workflow from the reviewed source revision. Never manufacture a tag by pushing whichever local image happens to have the expected name.

For authentication, grant only pull scope on the exact repository to the workload identity and verify an unrelated repository remains denied.

System changes

Changes a versioned image reference, repository authorization rule, supported daemon configuration, or release artifact according to the proven failure boundary.

Example output / evidence

Change review
Old: registry.example.com/team/api:2026.08.32
New: registry.example.com/team/api@sha256:4c4b0f4db44c8b88b7f00ecf269aaf6ba5cb6fd917cd92068f7da57d06d5608f
Evidence: signed release 2026.08.23
Scope: api service only
Rollback: previous digest sha256:90c0... retained

Security notes

Do not solve a private-image failure by making the repository public, disabling TLS, using an administrator token, or granting registry-wide read access.

Alternatives

Keep the current release on {{knownGoodRef}} while the missing artifact is rebuilt and reviewed independently.

Stop conditions

Stop if the proposed image digest lacks provenance, signature or release approval required by local policy, or if the change cannot be rolled back independently.

command

Pull the corrected reference for one explicit platform

caution

Pull the reviewed image reference only after manifest, identity, and platform evidence agree. Use an explicit platform when the deployment requires one, and capture the returned digest. This downloads layers and updates the local image store but does not start a container.

Why this step matters

A bounded pull confirms registry resolution, authorization, platform selection, and layer transfer without changing a running workload.

What to understand

Compare the returned digest with the independently approved release digest. A successful download of a different digest is a supply-chain discrepancy, not a successful repair.

Pulling can consume significant disk space and bandwidth. Check capacity and registry rate limits before production tests, especially on constrained CI runners.

System changes

Downloads image manifests and layers into the selected Docker daemon's local image store.

Syntax explained

docker pull: Downloads the selected manifest and referenced layers without starting a container.
--platform {{platformName}}: Requests the reviewed operating-system and architecture variant explicitly.
{{imageRef}}: Uses the corrected registry reference whose manifest and digest were already verified.

Command

Fill variables0/2 ready

Values stay on this page and are never sent or saved.

Platform Name{{platformName}}Required Docker platform in OS/architecture form.Image Ref{{imageRef}}Complete failing or corrected image reference, including registry and tag or digest.

docker pull --platform {{platformName}} {{imageRef}}

Example output / evidence

2026.08.23: Pulling from team/api
9f3f9f2d1a9b: Pull complete
4a0d9f8f32cd: Pull complete
Digest: sha256:4c4b0f4db44c8b88b7f00ecf269aaf6ba5cb6fd917cd92068f7da57d06d5608f
Status: Downloaded newer image for registry.example.com/team/api:2026.08.23

Checkpoint: Checkpoint: the exact artifact is locally available

docker pull --platform {{platformName}} {{imageRef}}

Continue whenThe pull exits 0 and reports the same digest recorded in approved release evidence.

Stop whenThe digest differs, the platform is substituted unexpectedly, disk capacity is insufficient, or the registry redirects to an unapproved host.

If this step fails

Manifest inspection succeeds but layer download fails.

Likely causeA blob endpoint, object store redirect, proxy rule, disk boundary, or registry backend failed after manifest resolution.

Safe checks

Record the first failing blob URL host without retaining its signed query.
Check daemon storage headroom and proxy exceptions.

ResolutionRepair the demonstrated blob-transfer path; keep the manifest reference unchanged.

Security notes

Do not copy signed layer URLs or authorization query parameters into tickets; they may grant temporary artifact access.

Alternatives

Use an isolated staging daemon for the first layer download when production storage or network policy makes a direct test inappropriate.

Stop conditions

Stop before deployment if the pulled digest is not exactly the approved digest.

verification

Verify the resolved digest in the deployment path

read-only

Render the actual deployment configuration, deploy through the normal controlled mechanism, and inspect the resulting container image reference and repository digest. Repeat the original operation from the same client or CI job so the fix proves the automation path, not only one terminal.

Why this step matters

The repair is complete only when the versioned deployment path selects the intended immutable artifact and the original failed workflow succeeds.

What to understand

For Compose, inspect the fully rendered service configuration before apply. For CI, record the resolved image input and digest in the job artifact. For orchestration, inspect the actual workload imageID after rollout.

Verify one negative control: an unauthorized identity or unrelated repository should remain denied. This proves the repair did not remove access control.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Syntax explained

docker image inspect: Reads the local image metadata, configuration, platform, and repository digests.
docker image ls --digests: Shows tags and immutable digests known to the selected daemon for the repository.

Command

Fill variables0/3 ready

Values stay on this page and are never sent or saved.

docker image inspect {{imageRef}} && docker image ls --digests {{registryHost}}/{{repositoryPath}}

Example output / evidence

RepoDigests: [registry.example.com/team/api@sha256:4c4b0f4db44c8b88b7f00ecf269aaf6ba5cb6fd917cd92068f7da57d06d5608f]
REPOSITORY                            TAG          DIGEST
registry.example.com/team/api         2026.08.23  sha256:4c4b0f4db44c...

Checkpoint: Checkpoint: deployment and local evidence agree

docker image inspect {{imageRef}}

Continue whenThe inspected repository digest, platform, and release metadata match the approved artifact and the original workflow exits successfully.

Stop whenAutomation still renders the old reference, the runtime digest differs, or authorization was broadened.

If this step fails

The manual pull works but Compose or CI still reports manifest unknown.

Likely causeAutomation renders another variable, uses another Docker context, or runs under a different registry identity.

Safe checks

Render the final Compose or CI image value.
Run docker context show in the failing automation boundary.

ResolutionCorrect the versioned automation input and repeat the original job; do not rely on a manually cached image.

Security notes

Store only the digest and necessary release metadata; do not export the complete image configuration when it contains sensitive labels or environment defaults.

Alternatives

Use the orchestrator's imageID field as runtime proof when the workload is not managed by the local Docker daemon.

Stop conditions

Do not close the incident while a manual test and the production automation resolve different references or identities.

verification

Observe the registry path and close with immutable evidence

read-only

Watch the next bounded pull, build, or rollout cycle and confirm that failed to resolve reference, manifest unknown, pull access denied, and no matching manifest do not recur. Record the proven cause, exact changed source, approved digest, affected contexts, verification, rollback point, and remaining uncertainty.

Why this step matters

One cached success may hide a remaining registry, platform, or automation problem. An uncached or independently scheduled cycle proves the durable path.

What to understand

Include a fresh runner or cleared test cache when local policy allows, so the result does not rely only on layers already present in one daemon.

Keep the last known-good digest until the observation window and normal rollout health checks complete.

System changes

No persistent change. This step reads client, daemon, registry, or manifest evidence and records it for comparison.

Example output / evidence

Observation window: 30 minutes
Original CI pull: PASS
Resolved digest: sha256:4c4b0f4db44c8b88b7f00ecf269aaf6ba5cb6fd917cd92068f7da57d06d5608f
Platform: linux/amd64
Original signatures: 0 recurrences
Unauthorized repository control: DENIED as expected
Rollback digest retained: yes

Checkpoint: Checkpoint: the repair survives a normal release cycle

docker buildx imagetools inspect {{imageRef}}

Continue whenThe same approved digest remains resolvable for the intended identity and platform with no recurrence in the original workflow.

Stop whenSuccess depends on one cache, one manually authenticated shell, a moved tag, or a weakened security control.

If this step fails

The error returns after the tag initially worked.

Likely causeA mutable tag moved or was deleted, retention removed a referenced manifest, credentials rotated incorrectly, or one runner retained stale configuration.

Safe checks

Inspect the tag digest again.
Compare runner contexts and credential audience.
Review registry retention and audit events.

ResolutionReturn to the immutable release digest, preserve audit evidence, and repair the release or retention process rather than repeatedly recreating the tag.

Security notes

Expire temporary credentials and remove diagnostic Docker config after evidence is retained.

Alternatives

Automate a read-only manifest existence and platform check before deployment using a workload identity and immutable digest.

Stop conditions

Do not close while the artifact depends on a mutable tag with no recorded digest or while any production runner still uses the failing reference.

Finish line

Verification checklist

The registry resolves the approved referencedocker buildx imagetools inspect {{imageRef}}The command exits 0 and returns the independently approved digest plus {{platformName}}.

The corrected image pulls without the original errordocker pull --platform {{platformName}} {{imageRef}}The pull exits 0, reports the approved digest, and emits no failed to resolve reference or manifest unknown response.

A negative authorization control remains enforceddocker buildx imagetools inspect {{registryHost}}/unauthorized-control:latestThe approved diagnostic identity remains denied for a repository it should not read.

Recovery guidance

Common problems and safe checks

failed to resolve reference ... manifest unknown

Likely causeThe registry cannot expose the requested tag or digest in the selected repository to this identity.

Safe checks

Print the exact {{imageRef}} from the failed automation.
docker buildx imagetools inspect {{imageRef}}
docker buildx imagetools inspect {{knownGoodRef}}

ResolutionCorrect the versioned reference, repository authorization, or approved publication pipeline according to the first differing check.

Docker image pull reference

pull access denied for repository, repository does not exist or may require docker login

Likely causeThe repository path is wrong, authentication was not used by this context, or the identity lacks pull scope.

Safe checks

docker context show
Confirm the fully qualified repository path.
Authenticate with a repository-scoped read token using --password-stdin.

ResolutionRepair the exact path or least-privilege pull authorization; do not make the repository public.

Docker login reference

failed to authorize: failed to fetch anonymous token

Likely causeDocker attempted anonymous token exchange, the token service is unreachable, or the repository scope and identity do not match.

Safe checks

curl --head https://{{registryHost}}/v2/
Inspect the Docker context and approved credential helper.
Verify registry and token-service DNS and TLS.

ResolutionRestore the approved token exchange and repeat the exact manifest inspection.

no matching manifest for linux/arm64/v8 in the manifest list entries

Likely causeThe image tag exists but no descriptor matches the requested platform.

Safe checks

docker buildx imagetools inspect {{imageRef}}
Record the daemon and requested platform.
Review the release build platform matrix.

ResolutionPublish and test the missing platform through the approved build pipeline or select a supported immutable release.

Docker multi-platform builds

x509: certificate signed by unknown authority

Likely causeThe daemon or builder does not trust the registry's complete certificate chain or approved internal CA.

Safe checks

Inspect the registry certificate chain from the failing network boundary.
Compare daemon or Desktop trust configuration with the registry owner's approved CA.

ResolutionInstall the approved CA through the supported daemon or Desktop trust path and keep verification enabled.

Manifest inspection works, but docker pull fails on a blob.

Likely causeLayer storage, object-store redirects, proxy exclusions, signed URL handling, rate limiting, or local disk capacity fails after manifest resolution.

Safe checks

Capture the first failing host and HTTP status without retaining signed query parameters.
Check Docker daemon disk usage and the approved proxy path.

ResolutionRepair the demonstrated layer-transfer or storage boundary without changing the manifest reference.

A manual pull succeeds while CI or Compose still fails.

Likely causeAutomation renders another image value, uses a different context or builder, or authenticates as another identity.

Safe checks

Render the final automation configuration.
Run docker context show in the failing job.
Compare the literal image reference and requested platform.

ResolutionFix the versioned automation input and rerun the original workflow; do not depend on one daemon's local cache.

The tag resolves to a different digest on a later retry.

Likely causeA mutable tag moved, was republished, or registry replication exposed inconsistent state.

Safe checks

Inspect the tag from each approved registry endpoint.
Compare registry audit events and signed release metadata.

ResolutionPin the approved digest, preserve audit evidence, and correct tag immutability or promotion policy before continuing.

After the procedure

Alternatives and next steps

Consider these alternatives

Keep the service on the previous immutable digest while the missing image is rebuilt through the normal release pipeline.
Use the registry's supported workload-identity or cloud credential helper rather than static credentials.
Use docker manifest inspect when Buildx is unavailable, and document the CLI's experimental status and any output differences.
Schedule the workload only on a platform already published when that is an approved temporary capacity decision; publish the missing architecture before restoring broad scheduling.
Add a pre-deployment manifest, digest, and platform gate in CI so the release fails before changing a production workload.

Operate it safely

Pin production deployments to immutable repository digests and keep the human release tag as descriptive metadata.
Make CI publish and verify every supported platform before it updates deployment references.
Add a read-only preflight that checks registry DNS and TLS, scoped authentication, manifest existence, approved digest, and requested platform.
Monitor registry token failures, manifest unknown rates, replication health, and retention events without logging credentials or signed layer URLs.
Record repository ownership, retention guarantees, credential rotation, and rollback digests in the service runbook.
Link the verified result to the Docker incident workflow and reuse the same evidence fields for future image-resolution events.

Reference

Frequently asked questions

What does Docker failed to resolve reference mean?

Docker or BuildKit did not obtain a usable manifest for the supplied image reference. The first failing layer can be registry DNS or TLS, token exchange, repository scope, an absent tag or digest, or platform selection. Preserve the complete error and test those boundaries in order.

What does manifest unknown mean?

The registry cannot return the requested manifest name to this caller. Usually the repository, tag, or digest is wrong or absent, but private registries may use the same response to hide content from an unauthorized identity.

Can docker login fix manifest unknown?

Only when authentication or repository authorization is the cause. A successful login does not create an absent tag, correct a repository typo, or add a missing architecture. Inspect the exact manifest after authenticating.

Why does the image work on amd64 but fail on arm64?

The tag may point to a single-platform manifest or an index without a linux/arm64 descriptor. Inspect the index and publish a tested arm64 variant or use a supported release; do not relabel an amd64 image.

Should I use latest when a release tag is missing?

No. latest is another mutable tag and may not exist or may select an unrelated release. Use an independently approved version or immutable digest.

Is it safe to configure the registry as insecure?

Not as a troubleshooting shortcut. That weakens server authentication and can expose credentials or artifacts. Repair the certificate chain, approved CA trust, DNS, or proxy path while keeping TLS verification enabled.

Why does docker pull work manually but the deployment still fails?

The deployment may render another variable, use another Docker context or BuildKit builder, request another platform, or authenticate as a different identity. Verify the final rendered reference inside the original automation boundary.

How do I prevent failed to resolve reference during releases?

Publish all required platforms first, record the immutable digest, verify it with the deployment identity, and update production only after the registry preflight succeeds. Retain the previous digest for rollback.

Recovery

Rollback

Restore the last known-good immutable image reference and remove only temporary credentials or local diagnostic state; registry history cannot be reconstructed from a missing tag unless the digest still exists.

Restore the previous deployment definition or Compose value that pins the last known-good image digest.
Redeploy through the normal release process and verify that the running container reports the expected digest and platform.
Remove temporary DOCKER_CONFIG data or log out from the registry on shared diagnostic hosts according to local credential policy.
If a tag was moved accidentally, preserve audit evidence and repoint it only through the registry owner's reviewed release procedure.

Evidence

Sources and review

Verified 2026-08-23Review due 2027-02-19

Docker image pull referenceofficial Docker image tag referenceofficial Docker login referenceofficial Docker manifest command referenceofficial Docker Buildx imagetools inspect referenceofficial Docker multi-platform buildsofficial Docker daemon proxy configurationofficial