What causes "Invalid container image format" in microsoft/aspire?

Pass a valid ContainerImageFormat value (Oci, Docker) or null instead of an arbitrary cast.

microsoft/aspire · error · ArgumentOutOfRangeException

Invalid container image format

Error message

Invalid container image format

What it means

The image output type is selected with a switch expression over ContainerImageFormat that handles Oci, Docker, and null (defaulting to docker); any other enum value falls into the throw arm of ArgumentOutOfRangeException. Because ContainerImageFormat only has those members in practice, this is an internal invariant guard against unexpected or out-of-range values.

Solutions

Pass a valid ContainerImageFormat value (Oci, Docker) or null instead of an arbitrary cast.
Validate config-driven format strings with Enum.TryParse before assigning ImageFormat.
Upgrade the Aspire.Hosting package if the value came from a newer version's enum.

Example fix

// before
var format = (ContainerImageFormat)int.Parse(config["format"]);
// after
if (!Enum.TryParse<ContainerImageFormat>(config["format"], out var format))
{
    throw new InvalidOperationException($"Unknown container image format '{config["format"]}'");
}

Defensive patterns

Strategy: validation

Validate before calling

if (format is not null && format is not ContainerImageFormat.Oci and not ContainerImageFormat.Docker)
{
    throw new ArgumentException($"Unsupported image format: {format}", nameof(format));
}

Type guard

bool IsKnownFormat(ContainerImageFormat? f) => f is null or ContainerImageFormat.Oci or ContainerImageFormat.Docker;

Try / catch

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (ArgumentOutOfRangeException ex)
{
    logger.LogError(ex, "Unknown ContainerImageFormat value {Value}.", ex.ActualValue);
}

Prevention

Never cast raw ints to ContainerImageFormat; use Enum.TryParse.
Assign ImageFormat only from known constants or parsed-and-validated config.
Avoid boxing/deserializing enum values without validation.

When it happens

Trigger: Passing an ImageFormat value to BuildImageAsync that is not Oci, Docker, or null — e.g. an invalid cast from an int to ContainerImageFormat producing an undefined enum value, or a future enum member added upstream without updating this switch.

Common situations: Parsing a format string from configuration into the enum without validation ((ContainerImageFormat)42); deserializing enum values from JSON; version skew between an app and a newer Aspire package that added a format.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs:68

            {
                arguments += $" --builder \"{builderName}\"";
            }

            // Add platform support if specified
            if (options?.TargetPlatform is not null)
            {
                arguments += $" --platform \"{options.TargetPlatform.Value.ToRuntimePlatformString()}\"";
            }

            // Add output format support if specified
            if (options?.ImageFormat is not null || !string.IsNullOrEmpty(options?.OutputPath))
            {
                var outputType = options?.ImageFormat switch
                {
                    ContainerImageFormat.Oci => "type=oci",
                    ContainerImageFormat.Docker => "type=docker",
                    null => "type=docker",
                    _ => throw new ArgumentOutOfRangeException(nameof(options), options.ImageFormat, "Invalid container image format")
                };

                if (!string.IsNullOrEmpty(options?.OutputPath))
                {
                    var archivePath = ResourceExtensions.GetContainerImageArchivePath(options.OutputPath, imageName);
                    outputType += $",dest={archivePath}";
                }

                arguments += $" --output \"{outputType}\"";
            }

            // Add build arguments if specified
            arguments += BuildArgumentsString(buildArguments);

            // Add build secrets if specified
            arguments += BuildSecretsString(buildSecrets);

            // Add stage if specified

View on GitHub (pinned to 25830f84bd)