What causes "Model must be a FoundryModel or a string model name." in microsoft/aspire?

Pass a FoundryModel instance or a string model name

microsoft/aspire · error · ArgumentException

Model must be a FoundryModel or a string model name.

Error message

Model must be a FoundryModel or a string model name.

What it means

Type filter in AddModelDeploymentForPolyglot: the 'model' argument of the AspireUnion parameter is neither a FoundryModel instance nor a string model name. The polyglot bridge supplied an unsupported type for the union parameter.

Solutions

Pass a FoundryModel instance or a string model name
Check the model value's type at the call site before invoking
If the value may be null or another type, throw or convert it before calling

Example fix

// before
object model = GetModel();
project.AddModelDeploymentForPolyglot("gpt-4o", model);

// after
FoundryModel model = GetModel();
project.AddModelDeploymentForPolyglot("gpt-4o", model);

Defensive patterns

Strategy: type-guard

Validate before calling

if (model is not (FoundryModel or string))
{
    throw new InvalidOperationException($"Unsupported model type {model?.GetType().Name}.");
}

Type guard

static bool IsValidModel(object? model) => model is FoundryModel or string;

Try / catch

try { project.AddModelDeploymentForPolyglot(name, model, version, format); }
catch (ArgumentException ex) when (ex.Message.Contains("FoundryModel or a string"))
{
    // Convert or reject the unsupported model value.
}

Prevention

Type model variables as FoundryModel or string, not object
Validate deserialized/config model values before calling
Never pass null as the model argument

When it happens

Trigger: Passing null, an enum, a custom model wrapper, or any object that is neither FoundryModel nor string as the model argument to AddModelDeploymentForPolyglot.

Common situations: Dynamic/deserialized model values of unexpected type in polyglot app hosts; a variable typed as object passed straight through; passing null where the parameter type allows it.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

    [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)