What causes "Terminal host at index {i} is null." in microsoft/aspire?

Filter out nulls before calling Initialize: terminalHosts = allHosts.Where(h => h is not null).ToList().

microsoft/aspire · error · ArgumentException

Terminal host at index

Error message

Terminal host at index {i} is null.

What it means

TerminalAnnotation.Initialize validates each element of the terminalHosts list and throws ArgumentException naming the offending index when a null element is found. This complements the non-null parameter check by catching nulls inside an otherwise non-null collection.

Solutions

Filter out nulls before calling Initialize: terminalHosts = allHosts.Where(h => h is not null).ToList().
Fix the producer that appended null so it only adds real TerminalHostResource instances (or throws at the source).
Validate the collection with a null-element check before initialization to fail with a clearer application-level error.

Example fix

// before
terminalAnnotation.Initialize(hostArray); // hostArray[2] == null

// after
terminalAnnotation.Initialize(hostArray.Where(h => h is not null).Cast<TerminalHostResource>().ToList());

Defensive patterns

Strategy: validation

Validate before calling

if (terminalHosts.Any(h => h is null))
    throw new ArgumentException("Terminal host list contains null entries.");

Type guard

static bool HasNoNulls(IReadOnlyList<TerminalHostResource?> hosts) => hosts.All(h => h is not null);

Try / catch

try
{
    terminalAnnotation.Initialize(terminalHosts);
}
catch (ArgumentException ex)
{
    logger.LogError(ex, "Null terminal host entry: {Message}", ex.Message);
}

Prevention

Build host lists with Add of non-null instances only; never pre-size arrays with null placeholders.
Filter nulls with Where(h => h is not null) before Initialize.
Fail fast at the producer if host creation yields null.

When it happens

Trigger: Passing a List<TerminalHostResource?> (or object[] built dynamically) that contains a null element at position i to Initialize — e.g. hosts collected via a loop that appends null on failure, or an array sized but not fully populated.

Common situations: Custom tooling that builds the host list with placeholder nulls; refactored code that changed Add logic so some entries never get assigned; deserialized/parsed host lists with missing entries.

Related errors

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

Appendix: source

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

    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>
/// Options for configuring a terminal session.
/// </summary>
[Experimental("ASPIRETERMINAL001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
public sealed class TerminalOptions
{
    private int _columns = 120;
    private int _rows = 30;

View on GitHub (pinned to 25830f84bd)