microsoft/aspire · error · InvalidOperationException

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

Error message

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

What it means

When InspectImageConfigAsync returns Status == Failed, the integration throws InvalidOperationException using the runtime-provided ErrorMessage when available, otherwise this fallback message. The inspection command executed but the runtime reported an error obtaining the image configuration.

Solutions

Run `docker image inspect <image>` manually to reproduce and see the underlying runtime error.
Authenticate to the registry (docker login) and retry the deployment.
Pre-pull the image (docker pull <image>) to ensure it exists locally with a valid config.
Check registry status/network and, if the local store is corrupted, prune and re-pull the image.

Example fix

// before (shell)
aspire deploy   # config inspect fails: image not found locally

// after
docker login myregistry.azurecr.io
docker pull myregistry.azurecr.io/myapp:latest
aspire deploy

Defensive patterns

Strategy: try-catch

Validate before calling

var proc = await Process.RunAsync("docker", "pull <image>");
if (proc.ExitCode != 0) throw new InvalidOperationException($"Image pull failed: {proc.Output}");

Try / catch

try
{
    await DeployToSandboxAsync(...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("failed to inspect image configuration"))
{
    logger.LogError(ex, "Image config inspection failed; re-authenticate and pre-pull the image.");
    throw;
}

Prevention

docker login before deployment.
Pre-pull the image so local state is valid.
Watch for tag deletions/retags between pipeline steps.

When it happens

Trigger: The runtime's image config inspection fails for the resolved reference — image not present locally and pull fails, registry authentication errors, corrupted local image store, or the tag/digest was removed between manifest and config inspection.

Common situations: Unauthenticated access to a private registry; image garbage-collected locally mid-deployment; registry outage or rate limit; image tag retagged/deleted after a previous successful inspection.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

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

    }

    internal static bool HasModeledCommandConfiguration(IResource resource) =>
        resource is ContainerResource { Entrypoint: { Length: > 0 } } ||
        resource.TryGetAnnotationsOfType<CommandLineArgsCallbackAnnotation>(out var callbacks) && callbacks.Any();

    private static async Task<ContainerImageMetadata> InspectLocalContainerImageAsync(PipelineStepContext context, string imageReference)
    {
        var runtime = await ResolveContainerRuntimeAsync(context).ConfigureAwait(false);
        var result = await runtime.InspectImageConfigAsync(imageReference, context.CancellationToken).ConfigureAwait(false);
        if (result.Status == ContainerImageInspectionStatus.Unsupported)
        {
            throw new NotSupportedException(
                $"Container runtime '{runtime.Name}' does not support image configuration inspection, which is required for Azure sandbox deployment.");
        }

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

        if (!result.TryGetConfig(out var config))
        {
            throw new InvalidOperationException($"Container runtime did not return image configuration for '{imageReference}'.");
        }

        return new ContainerImageMetadata(
            config.Entrypoint,
            config.Command,
            new Dictionary<string, string>(StringComparer.Ordinal),
            config.WorkingDirectory,
            new HashSet<string>(StringComparer.OrdinalIgnoreCase));
    }

    private static Task<IContainerRuntime> ResolveContainerRuntimeAsync(PipelineStepContext context)
    {

View on GitHub (pinned to 25830f84bd)