RicoSuter/NSwag · error · InvalidOperationException

No registered OpenAPI/Swagger document found for the…

Error message

No registered OpenAPI/Swagger document found for the document name '{documentName}'. Add with the AddSwagger()/AddOpenApi() methods in ConfigureServices().

What it means

GenerateAsync looks up the registered document settings by documentName and throws InvalidOperationException when no registration matches (or its settings are null). The request document name must exactly match a DocumentName registered via AddOpenApiDocument/AddSwaggerDocument.

Solutions

Ensure a document with the exact DocumentName is registered via AddOpenApiDocument/AddSwaggerDocument.
Fix the document name in the request URL or UseOpenApi(o => o.DocumentName = ...) to match the registration (names are case-sensitive).
Check for renamed documents after refactoring or upgrading NSwag.

Example fix

// before
app.UseOpenApi(o => o.DocumentName = "api");
services.AddOpenApiDocument(c => c.DocumentName = "v1");
// after
app.UseOpenApi(o => o.DocumentName = "v1");
services.AddOpenApiDocument(c => c.DocumentName = "v1");

Defensive patterns

Strategy: validation

Validate before calling

var registered = new HashSet<string>(StringComparer.Ordinal) { "v1", "v2" };
if (!registered.Contains(requestedDocumentName)) throw new ArgumentException($"Unknown document '{requestedDocumentName}'. Registered: {string.Join(",", registered)}");

Type guard

bool IsKnownDocument(string name, IEnumerable<string> registered) => registered.Contains(name, StringComparer.Ordinal);

Try / catch

try { var doc = await GenerateAsync(documentName); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("No registered OpenAPI/Swagger document")) { logger.LogWarning("Unknown document name {Name}", documentName); }

Prevention

Keep a single constant list of document names shared between registrations and any code that requests them.
Remember document names are case-sensitive; compare with the exact registered value.
After renaming a document, update UseOpenApi/UseSwaggerUi DocumentName and all client-generation references.

When it happens

Trigger: Requesting /swagger/{name}/swagger.json where {name} does not match any registered DocumentName (case-sensitive), or code calling GenerateAsync("wrongName") directly; also registering zero documents.

Common situations: Typo or casing mismatch in the URL; renaming DocumentName after upgrading; adding UseOpenApi with a documentName parameter that differs from the registered one; forgetting AddOpenApiDocument entirely.

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 RicoSuter/NSwag@63daf8fcc3 (2026-09-14). Data as JSON: /api/errors/3e12da3e0d64e542. Report an issue: GitHub.

Appendix: source

Thrown at src/NSwag.AspNetCore/OpenApiDocumentProvider.cs:48

            {
                throw new ArgumentNullException(nameof(documentName));
            }

            foreach (var group in _documents.GroupBy(g => g.DocumentName))
            {
                if (group.Count() > 1)
                {
                    throw new ArgumentException("The OpenAPI/Swagger document '" + group.Key + "' registered multiple times: " +
                        "Explicitly set the DocumentName property in " +
                        nameof(NSwagServiceCollectionExtensions.AddSwaggerDocument) + "() or " +
                        nameof(NSwagServiceCollectionExtensions.AddOpenApiDocument) + "().");
                }
            }

            var document = _documents.SingleOrDefault(g => g.DocumentName == documentName);
            if (document?.Settings == null)
            {
                throw new InvalidOperationException($"No registered OpenAPI/Swagger document found for the document name '{documentName}'. " +
                    $"Add with the AddSwagger()/AddOpenApi() methods in ConfigureServices().");
            }

            var generator = new AspNetCoreOpenApiDocumentGenerator(document?.Settings);
            return generator.GenerateAsync(_serviceProvider);
        }

        // Called by the <c>dotnet-getdocument</c> tool from the Microsoft.Extensions.ApiDescription.Server package.
        IEnumerable<string> IDocumentProvider.GetDocumentNames()
        {
            // DocumentName may be null. But, if it is, cannot generate the registered document.
            return _documents
                .Where(document => document.DocumentName != null)
                .Select(document => document.DocumentName);
        }

        // Called by the <c>dotnet-getdocument</c> tool from the Microsoft.Extensions.ApiDescription.Server package.
        async Task IDocumentProvider.GenerateAsync(string documentName, TextWriter writer)

View on GitHub (pinned to 63daf8fcc3)