16.1.3.3 Manifest Order Issue

A manifest order issue arises specifically with multi-architecture image manifest lists, where the sequence in which platform-specific variants are listed can, on certain registries or older client versions, affect which variant actually gets pulled when a client's platform-matching logic does not behave exactly as expected, producing a container that silently runs the wrong architecture's image despite the manifest list technically including the correct variant.

What a manifest list actually contains

A multi-architecture image tag does not point directly to a single image; it points to a manifest list (sometimes called an image index), which itself contains references to multiple architecture-specific manifests, each annotated with the platform it targets:

docker manifest inspect registry.example.com/my-api:1.4.0

{
  "manifests": [
    { "platform": { "architecture": "amd64", "os": "linux" }, "digest": "sha256:abc..." },
    { "platform": { "architecture": "arm64", "os": "linux" }, "digest": "sha256:def..." }
  ]
}

A correctly functioning client inspects this list and selects the entry matching its own platform, regardless of the order the entries appear in; the order is not supposed to matter for correct platform selection under the specification's intended behavior.

Where order has actually mattered in practice

Despite the specification not mandating order-dependent selection, certain older Docker client versions, certain registries with non-standard manifest list handling, and some third-party tooling built before broad multi-architecture adoption matured have exhibited behavior where the first listed entry was used as a fallback or default in ambiguous situations, rather than strictly matching on platform metadata:

docker manifest create registry.example.com/my-api:1.4.0 \
  registry.example.com/my-api:1.4.0-amd64 \
  registry.example.com/my-api:1.4.0-arm64

The order entries are added during manifest creation corresponds to their order in the resulting list, and on an affected client or registry, placing the less commonly needed architecture first could result in it being selected by default in edge cases where platform matching did not behave as strictly as the specification intends.

Diagnosing a manifest order issue

If a host is pulling and running an image that turns out to be for the wrong architecture despite the correct platform's manifest genuinely being present in the list, comparing the platform actually pulled against the platform that should have been selected isolates whether this is occurring:

docker pull registry.example.com/my-api:1.4.0
docker image inspect registry.example.com/my-api:1.4.0 --format '{{.Architecture}}'
uname -m

A mismatch here, despite the manifest list genuinely containing an entry for the correct architecture, points toward a platform selection problem on the client or registry side rather than a missing or incorrectly built variant.

Explicitly specifying platform to bypass selection ambiguity

Rather than relying on automatic platform selection from the manifest list at all, explicitly specifying the desired platform on pull removes any dependency on how the client or registry's own selection logic behaves:

docker pull --platform=linux/amd64 registry.example.com/my-api:1.4.0

docker run --platform=linux/amd64 registry.example.com/my-api:1.4.0

This sidesteps the ambiguity entirely by making the platform choice explicit rather than dependent on whatever default selection behavior a particular client or registry version happens to implement.

Verifying manifest list correctness after creation

After creating or updating a multi-architecture manifest list, directly inspecting and testing pulls for each intended platform confirms the list resolves correctly for every target architecture, rather than assuming the creation step succeeded correctly based only on the absence of an error:

docker manifest inspect registry.example.com/my-api:1.4.0 | jq '.manifests[].platform'

docker pull --platform=linux/amd64 registry.example.com/my-api:1.4.0
docker pull --platform=linux/arm64 registry.example.com/my-api:1.4.0

Testing an explicit pull for each platform the manifest list is supposed to support, immediately after publishing it, catches a manifest order or content issue before it has a chance to affect a real deployment relying on automatic platform selection.

Using buildx to avoid manual manifest list construction

Building and pushing multi-architecture images directly through docker buildx build --platform with the --push flag constructs the manifest list automatically and correctly, generally avoiding the kind of manual, order-dependent manifest construction that has historically been more prone to this class of issue:

docker buildx build --platform=linux/amd64,linux/arm64 -t registry.example.com/my-api:1.4.0 --push .

This is generally the more reliable approach for new multi-architecture image pipelines, compared to building each architecture-specific image separately and manually assembling them into a manifest list with docker manifest create, which is the path more likely to introduce ordering or metadata inconsistencies if not done carefully.

Registry-specific behavior differences

Different container registries have, at various points, implemented manifest list handling with subtly different behaviors, particularly around caching of manifest list responses and how aggressively they validate platform metadata on the entries within a list; an issue that reproduces against one registry but not another is worth specifically isolating to confirm whether it is genuinely client-side or specific to a particular registry's own handling:

docker manifest inspect registry-a.example.com/my-api:1.4.0
docker manifest inspect registry-b.example.com/my-api:1.4.0

Comparing the raw manifest list content returned by different registries for what should be an identical multi-architecture image can reveal a registry-specific transformation or caching behavior contributing to an otherwise puzzling, registry-dependent symptom.

Common mistakes

• Assuming a multi-architecture manifest list always selects the correct platform automatically without verifying this directly through an explicit pull test for each intended architecture.
• Manually constructing manifest lists with docker manifest create without testing the result across every target platform afterward.
• Not specifying --platform explicitly when pulling or running an image in a context where the correct architecture genuinely matters, relying entirely on automatic selection behavior.
• Overlooking registry-specific manifest list handling differences when an issue reproduces against one registry but not another.
• Preferring manual manifest assembly over docker buildx build --push, which constructs multi-architecture manifest lists more reliably for most modern use cases.

Manifest order issues are a narrower, more registry- and client-version-specific category of multi-architecture problem than a missing or incorrectly built platform variant, and the most reliable mitigations are explicit platform specification on pull and run, direct verification of every intended platform after publishing a manifest list, and preferring buildx's automated manifest list construction over manual assembly wherever practical.