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

microsoft/aspire · error · ArgumentOutOfRangeException

Invalid container image format

Error message

Invalid container image format

What it means

When translating ContainerImageFormat options into MSBuild properties for 'dotnet publish /t:PublishContainer', the switch only maps Docker and OCI. Any other value falls into the discard arm and throws ArgumentOutOfRangeException named on options.ImageFormat with message 'Invalid container image format'.

Solutions

Only pass ContainerImageFormat.Docker or ContainerImageFormat.Oci.
Validate/parse the value with Enum.IsEnumDefined before assigning ImageFormat.
Align package versions so the enum definition matches across projects.
Leave ImageFormat null to use the SDK default.

Example fix

// before
var options = new ContainerBuildOptions { ImageFormat = (ContainerImageFormat)42 };

// after
var fmt = (ContainerImageFormat)42;
var options = new ContainerBuildOptions
{
    ImageFormat = Enum.IsEnumDefined(fmt) && fmt != 0 ? fmt : null
};

Defensive patterns

Strategy: validation

Validate before calling

if (options.ImageFormat is { } fmt && !Enum.IsEnumDefined(fmt))
{
    throw new ArgumentException($"Unknown ContainerImageFormat: {fmt}");
}

Type guard

static bool IsValidImageFormat(ContainerImageFormat? f) => f is null || f is ContainerImageFormat.Docker or ContainerImageFormat.Oci;

Try / catch

try { await manager.BuildImageAsync(resource, opts, ct); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName is "options" && ex.Message.Contains("Invalid container image format"))
{
    // reset ImageFormat to null (SDK default) and retry
}

Prevention

Never cast raw ints to ContainerImageFormat without Enum.IsEnumDefined.
Keep package versions aligned so enum definitions match.
Leave ImageFormat null unless a specific format is required.
Parse config values with Enum.TryParse<ContainerImageFormat>.

When it happens

Trigger: Passing an undefined/out-of-range ContainerImageFormat enum value in ContainerBuildOptions.ImageFormat (e.g. an invalid cast of an int to the enum, or a value from a newer/older assembly version of the enum).

Common situations: Deserializing build options from configuration or JSON where an int is cast blindly to ContainerImageFormat; version mismatch between packages defining the enum; hand-written code passing (ContainerImageFormat)99.

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/142c4a41623a442f. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs:356

        if (GetLocalRegistryName(containerRuntime) is string localRegistry)
        {
            arguments += $" /p:LocalRegistry=\"{localRegistry}\"";
        }

        // Add additional arguments based on options
        if (!string.IsNullOrEmpty(options.OutputPath))
        {
            arguments += $" /p:ContainerArchiveOutputPath=\"{options.OutputPath}\"";
        }

        if (options.ImageFormat is not null)
        {
            var format = options.ImageFormat.Value switch
            {
                ContainerImageFormat.Docker => "Docker",
                ContainerImageFormat.Oci => "OCI",
                _ => throw new ArgumentOutOfRangeException(nameof(options), options.ImageFormat, "Invalid container image format")
            };
            arguments += $" /p:ContainerImageFormat=\"{format}\"";
        }

        if (options.TargetPlatform is not null)
        {
            // Use the appropriate MSBuild properties based on the number of RIDs
            var runtimeIds = options.TargetPlatform.Value.ToMSBuildRuntimeIdentifierString();
            var ridArray = runtimeIds.Split(';');

            if (ridArray.Length == 1)
            {
                // Single platform - use RuntimeIdentifier/ContainerRuntimeIdentifier
                arguments += $" /p:RuntimeIdentifier=\"{ridArray[0]}\"";
                arguments += $" /p:ContainerRuntimeIdentifier=\"{ridArray[0]}\"";
            }
            else
            {

View on GitHub (pinned to 25830f84bd)