RicoSuter/NSwag · error · NotSupportedException

This UI does not support multiple documents per UI: Do not…

Error message

This UI does not support multiple documents per UI: Do not use '{documentName}' placeholder in DocumentPath or Path.

What it means

NSwag's Swagger UI/ReDoc middleware supports serving exactly one document per UI middleware when the '{documentName}' placeholder is used in the UI or document path. If multiple documents are registered AND the placeholder is present in DocumentPath or Path, the middleware cannot expand it to a single value and throws NotSupportedException from UseSwaggerUiWithDocumentNamePlaceholderExpanding (called via UseSwaggerUi and UseReDoc).

Solutions

Remove the '{documentName}' placeholder from DocumentPath/Path so a single UI serves the first (single) document.
If you truly have multiple documents, use the placeholder-free overload and register each UI explicitly, or use UseSwaggerUi with the documents parameter.
Reduce registrations to one AddOpenApiDocument/AddSwaggerDocument call if multiple documents were unintentional.

Example fix

// before
app.UseSwaggerUi(options =>
{
    options.DocumentPath = "swagger/{documentName}/swagger.json";
    options.Path = "/swagger";
});
// after
app.UseSwaggerUi(options =>
{
    options.DocumentPath = "/swagger/v1/swagger.json";
    options.Path = "/swagger";
});

Defensive patterns

Strategy: validation

Validate before calling

// before UseSwaggerUi
var hasPlaceholder = options.DocumentPath?.Contains("{documentName}") == true || options.Path?.Contains("{documentName}") == true;
if (hasPlaceholder && numberOfRegisteredDocuments > 1)
    throw new InvalidOperationException("Placeholder paths require exactly one registered document.");

Type guard

bool IsSingleDocumentSetup(IEnumerable<string> documentNames) => documentNames.Take(2).Count() <= 1;

Try / catch

try { app.UseSwaggerUi(o => { o.Path = "/swagger"; o.DocumentPath = "/swagger/{documentName}/swagger.json"; }); }
catch (NotSupportedException ex) { logger.LogError(ex, "UI path config incompatible with registered documents"); throw; }

Prevention

Use the '{documentName}' placeholder only in true multi-document setups with per-document UI middleware.
Keep DocumentPath and Path consistent (both with or both without the placeholder).
Add a startup smoke test hitting /swagger to catch middleware config errors at boot.

When it happens

Trigger: Calling app.UseSwaggerUi(options) with options.DocumentPath or options.Path containing '{documentName}' while more than one OpenAPI document is registered in DI (multiple AddOpenApiDocument/AddSwaggerDocument calls).

Common situations: Copy-pasting the multi-document sample from docs but using the placeholder-based paths intended for single-document setups; registering a second API document later without updating the UI configuration.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of RicoSuter/NSwag@63daf8fcc3 (2026-09-14). Data as JSON: /api/errors/90ec91d11d087d08. Report an issue: GitHub.

Appendix: source

Thrown at src/NSwag.AspNetCore/Extensions/NSwagApplicationBuilderExtensions.cs:210

                else
                {
                    // Register single ui with multiple documents
                    if (registerMultiple(documents))
                    {
                        register(settings.ActualSwaggerDocumentPath, settings.ActualSwaggerUiPath);
                    }
                    else
                    {
                        // If multiple documents is not supported and only one document is registered
                        if (documents.Count() == 1)
                        {
                            register(
                                settings.ActualSwaggerDocumentPath.Replace("{documentName}", documents.First().DocumentName),
                                settings.ActualSwaggerUiPath.Replace("{documentName}", documents.First().DocumentName));
                        }
                        else
                        {
                            throw new NotSupportedException("This UI does not support multiple documents per UI: " +
                                "Do not use '{documentName}' placeholder in DocumentPath or Path.");
                        }
                    }
                }
            }
            else
            {
                if (settings.ActualSwaggerUiPath.Contains("{documentName}"))
                {
                    throw new ArgumentException("The SwaggerUiRoute cannot contain '{documentName}' placeholder when SwaggerRoute is missing the placeholder.");
                }

                // Register single ui with one document
                register(settings.ActualSwaggerDocumentPath, settings.ActualSwaggerUiPath);
            }
        }
    }
}

View on GitHub (pinned to 63daf8fcc3)