What causes "At least one terminal host is required." in microsoft/aspire?

Ensure at least one TerminalHostResource exists before calling Initialize; add the terminal host(s) to the application model first.

microsoft/aspire · error · ArgumentException

At least one terminal host is required.

Error message

At least one terminal host is required.

What it means

TerminalAnnotation.Initialize requires a non-empty set of terminal hosts; an empty list produces ArgumentException 'At least one terminal host is required.' An annotation with no hosts has no meaning, so the library fails fast rather than creating a useless terminal annotation.

Solutions

Ensure at least one TerminalHostResource exists before calling Initialize; add the terminal host(s) to the application model first.
Guard with a count check and skip creating the annotation entirely when there are no terminal hosts.
Debug why host creation returned empty (filters, conditions, or publish mode flags) if hosts were expected.

Example fix

// before
terminalAnnotation.Initialize(terminalHosts); // terminalHosts is empty

// after
if (terminalHosts.Count > 0)
{
    terminalAnnotation.Initialize(terminalHosts);
}

Defensive patterns

Strategy: validation

Validate before calling

if (terminalHosts is not { Count: > 0 })
    return; // nothing to initialize

Try / catch

try
{
    terminalAnnotation.Initialize(terminalHosts);
}
catch (ArgumentException ex)
{
    logger.LogError(ex, "No terminal hosts provided: {Message}", ex.Message);
}

Prevention

Verify terminal hosts were added to the application model before initializing the annotation.
Short-circuit annotation creation when the computed host list is empty.
Investigate empty host computation (filters, mode flags) if hosts were expected.

When it happens

Trigger: Calling TerminalAnnotation.Initialize with an empty collection (e.g. a list filtered down to zero hosts, or default-initialized list never populated) — reached via MaterializeTerminalHostsAsync, AddSyntheticTerminalAnnotation, BuildModel, or CreateHarness when no TerminalHostResource was created.

Common situations: Custom publish/terminal tooling that computes terminal hosts conditionally and ends up with none; tests constructing the annotation before adding any hosts; misconfigured harness where terminal hosts failed to be added to the model.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/TerminalAnnotation.cs:75

    /// <summary>
    /// Populates <see cref="TerminalHosts"/> exactly once. Called by the
    /// <see cref="BeforeStartEvent"/> subscriber installed by
    /// <see cref="TerminalResourceBuilderExtensions.WithTerminal{T}(IResourceBuilder{T}, Action{TerminalOptions}?)"/>.
    /// </summary>
    /// <exception cref="InvalidOperationException">Thrown when called more than once.</exception>
    internal void Initialize(IReadOnlyList<TerminalHostResource> terminalHosts)
    {
        ArgumentNullException.ThrowIfNull(terminalHosts);

        if (IsInitialized)
        {
            throw new InvalidOperationException("TerminalAnnotation has already been initialized.");
        }

        if (terminalHosts.Count == 0)
        {
            throw new ArgumentException("At least one terminal host is required.", nameof(terminalHosts));
        }

        for (var i = 0; i < terminalHosts.Count; i++)
        {
            if (terminalHosts[i] is null)
            {
                throw new ArgumentException($"Terminal host at index {i} is null.", nameof(terminalHosts));
            }
        }

        _terminalHosts = terminalHosts;
        IsInitialized = true;
    }
}

#pragma warning restore ASPIRETERMINAL001

/// <summary>

View on GitHub (pinned to 25830f84bd)