microsoft/aspire · error · ArgumentException

Catalog name cannot be null or whitespace.

Error message

Catalog name cannot be null or whitespace.

What it means

AspireValueAttribute's CatalogName property throws ArgumentException when the catalogName passed to the attribute constructor is null, empty, or whitespace. The catalog name is the root name of the generated value catalog and must be a real identifier for export naming. The attribute cannot function without it, so the library fails fast at construction.

Solutions

1. Pass a non-empty catalog name string to the AspireValueAttribute constructor.
2. If the name comes from configuration or another source, validate it with string.IsNullOrWhiteSpace before constructing the attribute.
3. Check that the value is not accidentally an uninitialized field or a defaulted optional parameter.

Example fix

// before
[AspireValue("")]
// after
[AspireValue("MyCatalog")]

if (string.IsNullOrWhiteSpace(catalogName))
{
    throw new ArgumentException("A non-empty catalog name is required.", nameof(catalogName));
}
var attr = new AspireValueAttribute(catalogName);

bool HasCatalogName(string? s) => !string.IsNullOrWhiteSpace(s);

When it happens

Trigger: Calling new AspireValueAttribute(null), new AspireValueAttribute(""), or new AspireValueAttribute(" ") — i.e., supplying a null/empty/whitespace-only catalog name to the attribute constructor.

Common situations: Programmatically constructing the attribute from config-driven data (e.g., a sourced name that is null because a config key was missing), string concatenation that produced an empty result, or a default string parameter left unset in source generators or scaffolding code.

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

• Partition key paths cannot contain null or empty strings.
• Address prefix must be a string or a parameter resource…
• Address prefix must be omitted, a string, or a parameter…
• All resources should be of the same kind when calling…
• apiPath is required when apiTarget is specified.

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

Appendix: source

Thrown at src/Aspire.Hosting/Ats/AspireValueAttribute.cs:33

/// <para>
/// The <paramref name="catalogName"/> becomes the root name of the generated value catalog in
/// guest SDKs. Nested static types are emitted as nested namespaces or classes under that root.
/// </para>
/// <para>
/// Exported values should be side-effect free and should not return handles or other runtime-bound
/// ATS types.
/// </para>
/// </remarks>
/// <param name="catalogName">The root name of the generated value catalog.</param>
[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = false, AllowMultiple = false)]
public sealed class AspireValueAttribute(string catalogName) : Attribute
{
    /// <summary>
    /// Gets the root name of the generated value catalog.
    /// </summary>
    public string CatalogName { get; } = !string.IsNullOrWhiteSpace(catalogName)
        ? catalogName
        : throw new ArgumentException("Catalog name cannot be null or whitespace.", nameof(catalogName));

    /// <summary>
    /// Gets or sets an optional override for the exported value name.
    /// </summary>
    public string? Name { get; set; }
}

View on GitHub (pinned to 25830f84bd)