RicoSuter/NSwag · error · ArgumentException

The SwaggerUiRoute cannot contain

Error message

The SwaggerUiRoute cannot contain '{documentName}' placeholder when SwaggerRoute is missing the placeholder.

What it means

When the Swagger UI route (Path) contains the '{documentName}' placeholder but the document route (DocumentPath/SwaggerRoute) does not, the middleware has no consistent way to expand the placeholder per document and throws ArgumentException during UseSwaggerUi/UseReDoc setup. The placeholder must appear in both routes or in neither.

Solutions

Add the '{documentName}' placeholder to DocumentPath as well, e.g. "/swagger/{documentName}/swagger.json".
Or remove the placeholder from Path so both routes are placeholder-free.
Ensure both routes consistently use or omit the placeholder before calling UseSwaggerUi/UseReDoc.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

bool uiHas = options.Path?.Contains("{documentName}") == true;
bool docHas = options.DocumentPath?.Contains("{documentName}") == true;
if (uiHas != docHas) throw new ArgumentException("'{documentName}' must appear in both Path and DocumentPath, or in neither.");

Type guard

bool IsConsistentPlaceholder(string path, string docPath) => path?.Contains("{documentName}") == docPath?.Contains("{documentName}");

Try / catch

try { app.UseSwaggerUi(configureUi); }
catch (ArgumentException ex) when (ex.Message.Contains("{documentName}")) { logger.LogError(ex, "Mismatched {documentName} placeholders in UI routes"); throw; }

Prevention

Always configure Path and DocumentPath as a pair; template both or neither.
Centralize the route strings in constants so they cannot drift apart.
Add a startup integration test that runs the middleware configuration.

When it happens

Trigger: app.UseSwaggerUi(options => { options.Path = "/swagger/{documentName}"; options.DocumentPath = "/swagger/doc.json"; }) — Path has the placeholder, DocumentPath does not.

Common situations: Hand-editing one route to include '{documentName}' for multi-document setups but forgetting to update the other; mixing samples from single- and multi-document documentation.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

                        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)