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

AddModelDeploymentForPolyglot accepts either a FoundryModel or a string model name. When a FoundryModel is supplied, modelVersion and format must be null because the model object already carries them; passing either throws this ArgumentException.

Solutions

  1. Remove the modelVersion and format arguments when passing a FoundryModel
  2. If you need an explicit version/format, pass the model name as a string with both modelVersion and format instead
  3. Set modelVersion and format to null in the calling code when a FoundryModel is used

Example fix

// before
project.AddModelDeploymentForPolyglot("gpt-4o", FoundryModel.FromName("gpt-4o"), "2024-11-20", "OpenAI");

// after
project.AddModelDeploymentForPolyglot("gpt-4o", FoundryModel.FromName("gpt-4o"));
Defensive patterns

Strategy: validation

Validate before calling

if (model is FoundryModel && (modelVersion is not null || format is not null))
{
    modelVersion = null;
    format = null;
}
project.AddModelDeploymentForPolyglot(name, model, modelVersion, format);

Try / catch

try { project.AddModelDeploymentForPolyglot(name, model, modelVersion, format); }
catch (ArgumentException ex) when (ex.Message.Contains("must be omitted"))
{
    // Retry without version/format when a FoundryModel was supplied.
}

Prevention

When it happens

Trigger: Calling AddModelDeploymentForPolyglot with a FoundryModel instance while also supplying a non-null modelVersion or format argument.

Common situations: Translating older string-based calls to FoundryModel without removing the now-redundant version/format arguments; copying a string-model call and only swapping the model argument for a FoundryModel.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Project/ProjectBuilderExtension.cs:308

    /// <summary>
    /// Adds a model deployment to the parent Microsoft Foundry resource.
    /// </summary>
    [AspireExport("addModelDeployment")]
    internal static IResourceBuilder<FoundryDeploymentResource> AddModelDeploymentForPolyglot(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> 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.AddModelDeployment(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.AddModelDeployment(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 a model deployment to the parent Microsoft Foundry resource of the Microsoft Foundry project.
    /// </summary>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the internal addModelDeployment dispatcher export.")]
    public static IResourceBuilder<FoundryDeploymentResource> AddModelDeployment(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        [ResourceName] string name,
        string modelName,
        string modelVersion,
        string format)
    {
        ArgumentNullException.ThrowIfNull(builder);

View on GitHub (pinned to 25830f84bd)