RicoSuter/NSwag · error · ArgumentNullException

document

Error message

document

What it means

The OpenApiSchemaResolver constructor throws ArgumentNullException when the document parameter is null. The resolver needs a non-null OpenApiDocument to append generated schemas to its root and inherits base-class behavior that also depends on the document.

Solutions

1. Ensure the OpenApiDocument is successfully created before constructing the resolver
2. Guard: if (document == null) handle/throw a descriptive error before construction
3. Rely on high-level generator APIs (OpenApiDocumentGenerator) which construct the resolver internally

Example fix

// before
var resolver = new OpenApiSchemaResolver(document, settings);
// after
if (document == null)
    throw new InvalidOperationException("Document must be loaded before schema resolution");
var resolver = new OpenApiSchemaResolver(document, settings);

if (document == null) throw new InvalidOperationException("Document not loaded");
var resolver = new OpenApiSchemaResolver(document, settings);

bool ready = document is OpenApiDocument;

try { resolver = new OpenApiSchemaResolver(document, settings); } catch (ArgumentNullException) { /* load document first */ }

When it happens

Trigger: Constructing OpenApiSchemaResolver with a null document, e.g. when document generation failed earlier and the null was propagated into schema resolution.

Common situations: Custom generator pipelines that build the resolver manually, or passing a document variable that was never assigned after an async load.

Related errors

• globalScopeNames
• items
• key
• This UI does not support multiple documents per UI: Do not…
• The SwaggerUiRoute cannot contain

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

Appendix: source

Thrown at src/NSwag.Core/OpenApiSchemaResolver.cs:30

namespace NSwag
{
    /// <summary>Appends a JSON Schema to the Definitions of a Swagger document.</summary>
    public class OpenApiSchemaResolver : JsonSchemaResolver
    {
        private readonly ITypeNameGenerator _typeNameGenerator;

        private OpenApiDocument Document => (OpenApiDocument)RootObject;

        /// <summary>Initializes a new instance of the <see cref="OpenApiSchemaResolver" /> class.</summary>
        /// <param name="document">The Swagger document.</param>
        /// <param name="settings">The settings.</param>
        /// <exception cref="ArgumentNullException"><paramref name="document" /> is <see langword="null" /></exception>
        public OpenApiSchemaResolver(OpenApiDocument document, JsonSchemaGeneratorSettings settings)
            : base(document, settings)
        {
            if (document == null)
            {
                throw new ArgumentNullException(nameof(document));
            }

            _typeNameGenerator = settings.TypeNameGenerator;
        }

        /// <summary>Appends the schema to the root object.</summary>
        /// <param name="schema">The schema to append.</param>
        /// <param name="typeNameHint">The type name hint.</param>
        public override void AppendSchema(JsonSchema schema, string typeNameHint)
        {
            if (!Document.Definitions.Values.Contains(schema))
            {
                var typeName = _typeNameGenerator.Generate(schema, typeNameHint, Document.Definitions.Keys);
                Document.Definitions[typeName] = schema;
            }
        }
    }
}

View on GitHub (pinned to 63daf8fcc3)