microsoft/aspire · error · InvalidOperationException

result.ErrorMessage ?? "Container runtime failed to inspect…

Error message

result.ErrorMessage ?? "Container runtime failed to inspect image manifest '{imageReference}'."

What it means

When the runtime's manifest inspection returns Status == Failed, the integration throws InvalidOperationException surfacing the runtime's own error message if present, otherwise this generic message. It means the inspection command ran but exited with an error (as opposed to being unsupported).

Solutions

Read the surfaced runtime ErrorMessage (or run `docker manifest inspect <image>` manually) to see the underlying cause.
Run docker login / podman login against the registry and retry.
Verify the image tag/digest exists in the registry and pre-pull it locally (docker pull <image>) before deploying.
Check network/proxy configuration and registry availability, then re-run the deployment.

Example fix

// before (shell)
aspire deploy   # fails: manifest inspect of myapp:latezt -> manifest unknown

// after
docker pull myregistry.azurecr.io/myapp:latest   # fix tag, authenticate
aspire deploy

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: ensure the image is pullable
var proc = await Process.RunAsync("docker", "pull <image>");
if (proc.ExitCode != 0) throw new InvalidOperationException($"Cannot pull image: {proc.Output}");

Try / catch

try
{
    await DeployToSandboxAsync(...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("failed to inspect image manifest"))
{
    logger.LogError(ex, "Manifest inspection failed; check registry auth and image tag.");
    throw;
}

Prevention

Authenticate to the registry before deploying (docker login).
Pre-pull images so inspection runs locally.
Validate tags exist in the registry before deployment.

When it happens

Trigger: InspectImageManifestAsync fails for the resolved image reference — e.g. the image is not present locally and cannot be pulled, the registry rejected the request (auth, rate limits), or the tag does not exist. The result's ErrorMessage, when set, becomes the thrown message.

Common situations: Typo in image tag so the pull/inspect fails; unauthenticated private registry (docker login missing); registry rate limiting; offline machine without a cached image; proxy/firewall blocking registry access.

Related errors

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

Appendix: source

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

    internal static async Task<string> ResolveContainerImageReferenceForDiskImageAsync(
        IContainerRuntime runtime,
        string imageReference,
        CancellationToken cancellationToken)
    {
        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}";

View on GitHub (pinned to 25830f84bd)