microsoft/aspire · error · ChannelNotFoundException

No channel found matching

Error message

No channel found matching '{query.RequestedChannel}'. Valid options are: {string.Join(", ", allChannels.Select(c => c.Name))}

What it means

TemplateNuGetConfigService.ResolveTemplatePackageAsync throws ChannelNotFoundException when the caller requests a template channel by name that does not exist in the known channel list. The message lists all valid channel names so the caller can pick one.

Solutions

Re-run with a valid channel name from the message's list (e.g. `stable`, `daily`, or the exact name shown).
Omit the channel flag to use the default/identity channel resolution.
Update hardcoded scripts/CI to the renamed channel value.

Example fix

// before
aspire new --channel weekly
// after
aspire new --channel stable

Defensive patterns

Strategy: validation

Validate before calling

// List valid channels first and validate input:
// aspire new --channel <name>  — only pass names from: aspire config list / docs
var valid = new HashSet<string>(allChannels.Select(c => c.Name), StringComparer.OrdinalIgnoreCase);
if (!string.IsNullOrEmpty(requestedChannel) && !valid.Contains(requestedChannel))
    throw new ArgumentException($"Unknown channel '{requestedChannel}'. Valid: {string.Join(", ", valid)}");

Try / catch

try { await service.ResolveTemplatePackageAsync(query, ct); }
catch (ChannelNotFoundException ex)
{
    // show ex.Message — it enumerates valid channel names
}

Prevention

Copy channel names from the CLI help/docs, never type from memory
Keep scripts using channel names updated after releases rename them
Prefer omitting the channel flag to use defaults

When it happens

Trigger: ResolveTemplatePackageAsync receives a query with a non-empty RequestedChannel that matches no channel name case-insensitively (e.g. `--channel stablex` or a typo like `9.0` when channels are named differently).

Common situations: Typo in `aspire` CLI channel flag; channel renamed between releases; scripts hardcoding an old channel name; using a version number where a named channel is expected.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Templating/TemplateNuGetConfigService.cs:274

        // falls back to nuget.org instead of the local packages. See docs/specs/cli-identity-sidecar.md.
        var hasLocalPackagesOverride = executionContext.IdentityPackagesDirectory is not null;
        var hasPrHives = hasLocalPackagesOverride ||
            (query.IncludePrHives &&
                (executionContext.GetHiveCount() > 0 ||
                    allChannels.Any(static c => c.Type is PackageChannelType.Explicit && HasInstalledLocalBuildPackageSource(c))));

        IEnumerable<PackageChannel> channels;
        if (isUnqualifiedLocalResolution)
        {
            channels = allChannels.Where(c =>
                c.IsBackedByLocalPackageDirectory &&
                string.Equals(c.Name, executionContext.IdentityChannel, StringComparison.OrdinalIgnoreCase));
        }
        else if (!string.IsNullOrEmpty(query.RequestedChannel))
        {
            var matchingChannel = allChannels.FirstOrDefault(c =>
                    string.Equals(c.Name, query.RequestedChannel, StringComparison.OrdinalIgnoreCase))
                ?? throw new ChannelNotFoundException(
                    $"No channel found matching '{query.RequestedChannel}'. Valid options are: " +
                    $"{string.Join(", ", allChannels.Select(c => c.Name))}");
            channels = [matchingChannel];
        }
        else if (!string.IsNullOrWhiteSpace(query.SourceOverride))
        {
            // Every channel would query the same explicit source, so querying PR/local channels as
            // well would attach identical results to whichever channel finishes first. Keep the
            // implicit channel as the deterministic owner unless the user requested a channel.
            channels = allChannels.Where(c => c.Type is PackageChannelType.Implicit);
        }
        else
        {
            // If there are hives (PR build directories), include all channels.
            // Otherwise, only use the implicit/default channel to avoid prompting.
            channels = hasPrHives
                ? allChannels
                : allChannels.Where(c => c.Type is PackageChannelType.Implicit);

View on GitHub (pinned to 25830f84bd)