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

AddDeploymentForPolyglot only accepts two shapes for the model argument: a FoundryModel instance or a string model name (with version and format). Any other type (or null) falls into the switch's discard arm and throws this ArgumentException.

Solutions

Pass a FoundryModel instance or a string model name
If the value can be null, check it before calling and fail fast with your own message

Example fix

// before
object model = GetModel();
builder.AddDeploymentForPolyglot("deploy", model);
// after
if (model is not (FoundryModel or string)) throw new InvalidOperationException($"Unsupported model: {model?.GetType().Name}");
builder.AddDeploymentForPolyglot("deploy", model);

Defensive patterns

Strategy: type-guard

Validate before calling

if (model is null) throw new ArgumentNullException(nameof(model));

Type guard

bool IsValidModelArg(object? m) => m is FoundryModel or string;

Try / catch

try { builder.AddDeploymentForPolyglot(name, model); }
catch (ArgumentException ex) when (ex.Message.Contains("FoundryModel or a string")) { /* normalize model to FoundryModel or string */ }

Prevention

Type the model parameter/variable as FoundryModel or string at the call site
Null-check or handle failed lookups before invoking the API
Avoid dynamic/object-typed intermediaries for the model value

When it happens

Trigger: Passing null, or an object of an unexpected type (e.g. a custom model wrapper) as the model parameter of AddDeploymentForPolyglot.

Common situations: Passing a variable typed object/dynamic; refactoring changed the model type; passing null after a failed lookup that returned null instead of throwing.

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/0d5ecf5e59dd65ee. Report an issue: GitHub.

Appendix: source

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

    [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);
    ///
    /// var aiFoundry = builder.AddFoundry("aiFoundry");
    /// var gpt5mini = aiFoundry.AddDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

View on GitHub (pinned to 25830f84bd)