microsoft/aspire · error · InvalidOperationException

Container image ' ' does not contain a linux/amd64 manifest…

Error message

Container image '{imageReference}' does not contain a linux/amd64 manifest with an immutable digest.

What it means

Sandbox deployment requires an immutable linux/amd64 manifest digest. After inspection succeeds, TryGetManifest("linux", "amd64") is used to find that manifest; if the image has no linux/amd64 entry in its manifest list, deployment cannot proceed and throws InvalidOperationException.

Solutions

Build or select a multi-arch image that includes linux/amd64: docker buildx build --platform linux/amd64 and push it.
Choose a different base image that publishes linux/amd64 manifests.
Verify the image's platforms with `docker manifest inspect <image>` and confirm a linux/amd64 entry exists.
If the local runtime hides the platform entry, pre-pull with `--platform linux/amd64` and retry.

Example fix

// before
ARG base=mcr.microsoft.com/dotnet/runtime:10.0-noble-arm64v8

// after
ARG base=mcr.microsoft.com/dotnet/runtime:10.0-noble
# and build/push with:
# docker buildx build --platform linux/amd64 -t myregistry.azurecr.io/myapp:latest --push .

Defensive patterns

Strategy: validation

Validate before calling

var json = await GetManifestJsonAsync("docker", $"manifest inspect {image}");
using var doc = JsonDocument.Parse(json);
bool hasAmd64 = doc.RootElement.TryGetProperty("manifests", out var ms) &&
    ms.EnumerateArray().Any(m =>
        m.TryGetProperty("platform", out var p) &&
        p.TryGetProperty("architecture", out var a) && a.GetString() == "amd64" &&
        p.TryGetProperty("os", out var o) && o.GetString() == "linux");
if (!hasAmd64) throw new InvalidOperationException($"{image} lacks linux/amd64 manifest.");

Prevention

Build and push with --platform linux/amd64 (or multi-arch) for sandbox targets.
Inspect manifest platforms with `docker manifest inspect` before deploying.
Avoid arm64-only or windows-only base images for sandbox deployments.

When it happens

Trigger: Inspecting an image whose multi-arch manifest list lacks a linux/amd64 platform entry (e.g. an arm64-only or windows-only image), or inspecting a single-platform image where the runtime did not expose the expected platform manifest.

Common situations: Using an arm64-only image on the deployment pipeline; building/pushing an image for the wrong platform; images built with --platform windows/amd64 for Windows containers being deployed to Linux sandboxes.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/cc004bbbd55457e0. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxContainerDeployment.cs:1023

        ArgumentNullException.ThrowIfNull(runtime);
        ArgumentException.ThrowIfNullOrWhiteSpace(imageReference);

        var result = await runtime.InspectImageManifestAsync(imageReference, cancellationToken).ConfigureAwait(false);
        if (result.Status == ContainerImageInspectionStatus.Unsupported)
        {
            throw new NotSupportedException(
                $"Container runtime '{runtime.Name}' does not support image manifest inspection, which is required for Azure sandbox deployment.");
        }

        if (result.Status == ContainerImageInspectionStatus.Failed)
        {
            throw new InvalidOperationException(
                result.ErrorMessage ?? $"Container runtime failed to inspect image manifest '{imageReference}'.");
        }

        if (!result.TryGetManifest("linux", "amd64", out var manifest))
        {
            throw new InvalidOperationException(
                $"Container image '{imageReference}' does not contain a linux/amd64 manifest with an immutable digest.");
        }

        return CreateDigestImageReference(imageReference, manifest.Digest);
    }

    private static string CreateDigestImageReference(string imageReference, string digest)
    {
        var digestSeparator = imageReference.IndexOf('@');
        if (digestSeparator >= 0)
        {
            return $"{imageReference[..digestSeparator]}@{digest}";
        }

        var lastSlash = imageReference.LastIndexOf('/');
        var lastColon = imageReference.LastIndexOf(':');
        var repository = lastColon > lastSlash ? imageReference[..lastColon] : imageReference;

View on GitHub (pinned to 25830f84bd)