What causes "The export language cannot be empty." in microsoft/aspire?

Pass an explicit language name such as "TypeScript" in the exportApi request.

microsoft/aspire · error · LocalRpcException

-32602

-32602

Error message

The export language cannot be empty.

What it means

ExportApi validates that the 'language' argument is a non-empty, non-whitespace string before doing any work, throwing an invalid JSON-RPC request error (code -32602) when it is empty. The language selects which registered code generator and exporter will produce the API reference document.

Solutions

Pass an explicit language name such as "TypeScript" in the exportApi request.
Check the config/CLI flag that feeds the language value and ensure it is set before invoking exportApi.
List supported languages (see the resolver's registered code generators) and pick a valid one.

Example fix

// before
await rpc.InvokeAsync<JsonElement>("exportApi", new { language = "", packageName = "Aspire.Hosting", packageVersion = "9.0.0" });
// after
await rpc.InvokeAsync<JsonElement>("exportApi", new { language = "TypeScript", packageName = "Aspire.Hosting", packageVersion = "9.0.0" });

Defensive patterns

Strategy: validation

Validate before calling

if (!language || !language.trim()) {
  throw new Error('language must be a non-empty string before calling exportApi');
}

Type guard

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

Try / catch

try {
  await rpc.InvokeAsync('exportApi', req);
} catch (err) {
  if (err.code === -32602 && err.message.includes('export language cannot be empty')) {
    req.language = defaultLanguage; // retry with configured default
  } else throw err;
}

Prevention

Validate all exportApi string arguments (language, packageName, packageVersion) with a non-empty check before invoking.
Read language from a single well-typed config source rather than ad-hoc variables.
Fail fast at script start when required export options are unset.
Use named (not positional) arguments in the JSON-RPC request to avoid slot confusion.

When it happens

Trigger: Invoking the JSON-RPC 'exportApi' method with language set to "", null-coerced empty, or whitespace (e.g., " "), typically because the calling tool passed an unset variable or misread configuration into the language field.

Common situations: A CLI or IDE extension reads the target language from config or a command-line flag that was never set; a script template leaves a placeholder like {language} unexpanded to empty; a caller passes the wrong argument positionally so an empty string lands in the language slot.

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/73a62d2a3020604a. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.RemoteHost/CodeGeneration/CodeGenerationService.cs:303

    /// The version label to record for <paramref name="packageName"/>. The caller owns its accuracy;
    /// see <see cref="ApiReferenceExportOptions.PackageVersion"/>.
    /// </param>
    /// <param name="cancellationToken">A token to cancel the export.</param>
    /// <returns>The language provider's API reference document, verbatim.</returns>
    [JsonRpcMethod(ExportApiMethodName)]
    public JsonElement ExportApi(
        string language,
        string packageName,
        string packageVersion,
        CancellationToken cancellationToken)
    {
        using var rpcActivity = _profilingTelemetry.StartJsonRpcServerCall(ExportApiMethodName);
        try
        {
            _authenticationState.ThrowIfNotAuthenticated();
            if (string.IsNullOrWhiteSpace(language))
            {
                throw CreateInvalidExportRequest("The export language cannot be empty.");
            }
            if (string.IsNullOrWhiteSpace(packageName))
            {
                throw CreateInvalidExportRequest("The export package name cannot be empty.");
            }
            if (string.IsNullOrWhiteSpace(packageVersion))
            {
                throw CreateInvalidExportRequest("The export package version cannot be empty.");
            }

            _logger.LogDebug(">> exportApi({Language}, {PackageName}, {PackageVersion})", language, packageName, packageVersion);
            var sw = System.Diagnostics.Stopwatch.StartNew();

            var generator = _resolver.GetCodeGenerator(language);
            if (generator is null)
            {
                throw CreateInvalidExportRequest(BuildNoCodeGeneratorMessage(language));
            }

View on GitHub (pinned to 25830f84bd)