microsoft/aspire · error · ArgumentException

Unknown language

Error message

Unknown language: '{explicitLanguageId}'

What it means

When an explicit language id is supplied to project selection, LanguageService looks it up via language discovery; unknown ids are reported to the user and surfaced as ArgumentException naming the parameter. This prevents silently creating a project for a mis-typed language.

Solutions

1. Run the command without the language flag to see the list of supported language ids and pick interactively
2. Correct the language id to one of the supported values reported by language discovery
3. Clear or update any persisted selection in aspire.config.json that references the removed language

Example fix

// before
aspire new --language csharp   # unknown id
// after
aspire new --language dotnet   # supported id

var supported = languageDiscovery.GetLanguages().Select(l => l.Id).ToHashSet(StringComparer.OrdinalIgnoreCase);
if (!string.IsNullOrWhiteSpace(langId) && !supported.Contains(langId))
    throw new ArgumentException($"Unknown language: '{langId}'. Supported: {string.Join(", ", supported)}");

try { var sel = await svc.GetOrPromptForProjectSelectionAsync(langId, ...); }
catch (ArgumentException ex) when (ex.ParamName == nameof(explicitLanguageId))
{
    // fall back to interactive selection
    sel = await svc.GetOrPromptForProjectSelectionAsync(null, ...);
}

When it happens

Trigger: Calling GetOrPromptForProjectSelectionAsync with a languageId (e.g. from a CLI flag or saved setting) that GetLanguageById does not recognize.

Common situations: Typing 'csharp' vs supported ids like 'dotnet'/'python'/'java', an outdated saved selection in aspire.config after a language was renamed or removed, or scripting the CLI with a wrong value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Polyglot skeleton not yet supported for language
• Unsupported channel ' '. Available channels
• Already connected to AppHost backchannel.
• Already connected to
• AppHost is incompatible with the CLI. The AppHost must be…

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

Appendix: source

Thrown at src/Aspire.Cli/Projects/LanguageService.cs:129

        var selection = await GetOrPromptForProjectSelectionAsync(explicitLanguageId, saveLanguageSelection, cancellationToken);

        return selection.Project;
    }

    /// <inheritdoc />
    public async Task<AppHostProjectSelection> GetOrPromptForProjectSelectionAsync(
        string? explicitLanguageId = null,
        bool saveLanguageSelection = true,
        CancellationToken cancellationToken = default)
    {
        // If explicitly specified, use that
        if (!string.IsNullOrWhiteSpace(explicitLanguageId))
        {
            var language = _languageDiscovery.GetLanguageById(explicitLanguageId);
            if (language is null)
            {
                _interactionService.DisplayError($"Unknown language: '{explicitLanguageId}'");
                throw new ArgumentException($"Unknown language: '{explicitLanguageId}'", nameof(explicitLanguageId));
            }

            return new AppHostProjectSelection(_projectFactory.GetProject(language), ShouldPersistSelection: false);
        }

        // Check if configured
        var configuredProject = await GetConfiguredProjectAsync(cancellationToken);
        if (configuredProject is not null)
        {
            return new AppHostProjectSelection(configuredProject, ShouldPersistSelection: false);
        }

        // Prompt for selection
        var (selectedProject, selectedLanguage) = await PromptForProjectWithLanguageAsync(cancellationToken);

        // Save the language ID
        if (saveLanguageSelection)
        {

View on GitHub (pinned to 25830f84bd)