microsoft/aspire · error · ArgumentException

Model version and format are required when the model is…

Error message

Model version and format are required when the model is provided as a string.

What it means

AddModelDeploymentForPolyglot requires that when the model is given as a plain string, both modelVersion and format are also supplied, since a bare name does not carry them. If either is null, the switch throws this ArgumentException for the string case.

Solutions

  1. Supply both modelVersion and format when the model is a string name
  2. Use a FoundryModel instance instead of a string so version and format are embedded
  3. Fill in the missing argument (e.g. the format) that was left null

Example fix

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

// after
project.AddModelDeploymentForPolyglot("gpt-4o", "gpt-4o", "2024-11-20", "OpenAI");
Defensive patterns

Strategy: validation

Validate before calling

if (model is string && (modelVersion is null || format is null))
{
    throw new InvalidOperationException("string models require both modelVersion and format.");
}
project.AddModelDeploymentForPolyglot(name, model, modelVersion, format);

Try / catch

try { project.AddModelDeploymentForPolyglot(name, model, modelVersion, format); }
catch (ArgumentException ex) when (ex.Message.Contains("are required"))
{
    // Supply version/format or switch to FoundryModel.
}

Prevention

When it happens

Trigger: Calling AddModelDeploymentForPolyglot with a string model name but leaving modelVersion or format (or both) null.

Common situations: Porting code from a FoundryModel-based call to a string-based one without adding version and format; assuming defaults exist for string model names; partially filling only one of the two arguments.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    /// </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);
        ArgumentException.ThrowIfNullOrEmpty(name);
        return builder.ApplicationBuilder.CreateResourceBuilder(builder.Resource.Parent).AddDeployment(name, modelName, modelVersion, format);

View on GitHub (pinned to 25830f84bd)