microsoft/aspire · error · ArgumentException

Model version and format must be omitted when using a…

Error message

Model version and format must be omitted when using a FoundryModel.

What it means

AddDeploymentForPolyglot accepts either a FoundryModel object or a plain string model name plus version and format. When a FoundryModel is passed, the version and format are already embedded in the model, so supplying modelVersion or format is contradictory and throws this ArgumentException.

Solutions

1. Remove the modelVersion and format arguments when passing a FoundryModel
2. If you need explicit version/format, pass the model as a string with both modelVersion and format instead

Example fix

// before
builder.AddDeploymentForPolyglot("deploy", foundryModel, "2024-10-01", "OpenAI");
// after
builder.AddDeploymentForPolyglot("deploy", foundryModel);

if (model is FoundryModel && (modelVersion is not null || format is not null))
    throw new ArgumentException("Do not pass modelVersion/format with a FoundryModel.");

bool IsFoundryModel(object? m) => m is FoundryModel;

try { builder.AddDeploymentForPolyglot(name, model, version, format); }
catch (ArgumentException ex) when (ex.Message.Contains("must be omitted")) { /* drop version/format args */ }

When it happens

Trigger: Calling builder.AddDeploymentForPolyglot(name, foundryModelInstance, modelVersion: "1.0", format: "OpenAI") — passing any non-null version/format alongside a FoundryModel.

Common situations: Copy-pasting code that used the string overload then swapping in a FoundryModel without removing the version/format arguments.

Related errors

• Model version and format are required when the model is…
• Model must be a FoundryModel or a string model name.
• Array params contains empty item
• Array params contains null item
• At least one exporting assembly name is required.

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/FoundryExtensions.cs:105

    /// <summary>
    /// Adds a Microsoft Foundry deployment resource to a Microsoft Foundry resource.
    /// </summary>
    [AspireExport("addDeployment")]
    internal static IResourceBuilder<FoundryDeploymentResource> AddDeploymentForPolyglot(
        this IResourceBuilder<FoundryResource> builder,
        [ResourceName] string name,
        [AspireUnion(typeof(FoundryModel), typeof(string))] object model,
        string? modelVersion = null,
        string? format = null)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(model);
        ArgumentException.ThrowIfNullOrEmpty(name);

        return model switch
        {
            FoundryModel foundryModel when modelVersion is null && format is null => builder.AddDeployment(name, foundryModel),
            FoundryModel => throw new ArgumentException("Model version and format must be omitted when using a FoundryModel.", nameof(modelVersion)),
            string modelName when modelVersion is not null && format is not null => builder.AddDeployment(name, modelName, modelVersion, format),
            string => throw new ArgumentException("Model version and format are required when the model is provided as a string.", nameof(modelVersion)),
            _ => throw new ArgumentException("Model must be a FoundryModel or a string model name.", nameof(model))
        };
    }

    /// <summary>
    /// Adds and returns a Microsoft Foundry Deployment resource to the application model using a <see cref="FoundryModel"/>.
    /// </summary>
    /// <param name="builder">The Microsoft Foundry resource builder.</param>
    /// <param name="name">The name of the Microsoft Foundry Deployment resource.</param>
    /// <param name="model">The model descriptor, using the <see cref="FoundryModel"/> class like so: <code lang="csharp">aiFoundry.AddDeployment(name: "chat", model: FoundryModel.OpenAI.Gpt5Mini)</code></param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <remarks>
    /// <example>
    /// Create a deployment for the OpenAI GTP-5-mini model:
    /// <code lang="csharp">
    /// var builder = DistributedApplication.CreateBuilder(args);

View on GitHub (pinned to 25830f84bd)