What causes "Unknown schema type found in normalizer: {schema}" in OpenAPITools/openapi-generator?

Search the spec for explicit nulls around schemas: grep for ': null', ': ~', empty '$ref: ""' and for keys like items/additionalProperties with no value; fill them with real schema nodes or remove the keys.

OpenAPITools/openapi-generator · error · RuntimeException

Unknown schema type found in normalizer: {schema}

Error message

Unknown schema type found in normalizer: {schema}

What it means

OpenAPINormalizer.normalizeSchema dispatches on known Schema subtypes (binary/composite types earlier, then BooleanSchema, IntegerSchema, and a final 'schema instanceof Schema' fallback to normalizeSimpleSchema). The trailing else throws only when the value matches NONE of the branches - since the parameter is statically typed Schema, in practice that means the schema reached the normalizer as null (or an implementation not accepted by any branch). It is an internal invariant guard: something upstream produced an unrecognizable schema node, most often an explicit null in a schema list or property produced by lenient parsing or by programmatic spec construction.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:1067

                result.setAdditionalProperties(anyTypeNullable);
            } else {
                Schema normalized = normalizeSchema(additionalProperties, visitedSchemas);
                if (getRule(NORMALIZE_31SPEC)) {
                    // capture the normalized value schema (e.g. an OAS 3.1 `type: [array, "null"]`
                    // value is rewritten to a proper array schema), which would otherwise be lost.
                    result.setAdditionalProperties(normalized);
                }
            }

            return result;
        } else if (schema instanceof BooleanSchema) {
            normalizeBooleanSchema(schema, visitedSchemas);
        } else if (schema instanceof IntegerSchema) {
            normalizeIntegerSchema(schema, visitedSchemas);
        } else if (schema instanceof Schema) {
            return normalizeSimpleSchema(schema, visitedSchemas);
        } else {
            throw new RuntimeException("Unknown schema type found in normalizer: " + schema);
        }
        return schema;
    }

    /**
     * Normalize reference schema with allOf to support sibling properties
     *
     * @param schema         Schema
     */
    protected void normalizeReferenceSchema(Schema schema) {
        if (schema.getType() != null || schema.getTypes() != null && !schema.getTypes().isEmpty()) {
            // clears type(s) given that $ref is set
            schema.setType(null);
            schema.setTypes(null);
            LOGGER.warn("Type(s) cleared (set to null) given $ref is set to {}.", schema.get$ref());
        }

        if (schema.getTitle() != null || schema.getDescription() != null

View on GitHub (pinned to fcec517be3)

Solutions

Search the spec for explicit nulls around schemas: grep for ': null', ': ~', empty '$ref: ""' and for keys like items/additionalProperties with no value; fill them with real schema nodes or remove the keys.
Run a strict validator ('openapi-generator-cli validate') and fix structural diagnostics before normalizing.
If the spec is machine-generated, post-process it (jq/YAML round-trip) to drop null-valued schema nodes before feeding openapi-generator.
If you use a custom NORMALIZER_CLASS, audit it for null passthrough into normalizeSchema; guard its own normalize helpers against null.
With a clean spec but a persistent failure, minimize to the one schema that triggers it and report upstream - this guard firing indicates an unrecognized node shape.

Example fix

# before
components:
  schemas:
    PetList:
      type: array
      items:        # null items -> unrecognizable schema node
# after
components:
  schemas:
    PetList:
      type: array
      items:
        $ref: '#/components/schemas/Pet'

Defensive patterns

Strategy: validation

Validate before calling

// Reject null/empty schema nodes before normalization
OpenAPI api = ...;
Map<String, Schema> schemas = api.getComponents().getSchemas();
schemas.forEach((name, s) -> {
    if (s == null) throw new IllegalStateException("Null schema: " + name);
    if (s.getItems() == null && "array".equals(s.getType()))
        throw new IllegalStateException("Array without items: " + name);
    if (s.get$ref() != null && s.get$ref().isEmpty())
        throw new IllegalStateException("Empty $ref: " + name);
});

Try / catch

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unknown schema type found in normalizer")) {
        // schema node was null/unrecognizable: audit spec for null schema keys (items:, additionalProperties: ~)
        throw new GenerationFailure("Spec contains null/invalid schema node", e);
    }
    throw e;
}

Prevention

Run strict spec validation before generation so malformed nodes fail with precise locations.
Lint templated YAML output for ': null' / '~' schema values.
When mutating parsed specs programmatically, never put null into schema slots.

When it happens

Trigger: A spec containing explicit null schema nodes: 'items:' with no value (YAML ~), 'additionalSchema: null', empty '$ref: ""', a mapping that deserialized to null and is later normalized; an OpenAPI object built programmatically where a property/composed entry was set to null; a custom NORMALIZER_CLASS (error [13]/[14]) that itself passes null into normalize paths.

Common situations: Specs emitted by other tooling with empty/null nodes that the parser tolerates; templated YAML (Helm/Jinja) rendering a schema key with an empty variable; programmatic pipelines mutating components.schemas before generation.

Related errors

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/ddf545d6b327e1d7. Report an issue: GitHub.