{"record":{"id":"ddf545d6b327e1d7","repo":"OpenAPITools/openapi-generator","slug":"unknown-schema-type-found-in-normalizer-schema","errorCode":null,"errorMessage":"Unknown schema type found in normalizer: {schema}","messagePattern":"Unknown schema type found in normalizer: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java","lineNumber":1067,"sourceCode":"                result.setAdditionalProperties(anyTypeNullable);\n            } else {\n                Schema normalized = normalizeSchema(additionalProperties, visitedSchemas);\n                if (getRule(NORMALIZE_31SPEC)) {\n                    // capture the normalized value schema (e.g. an OAS 3.1 `type: [array, \"null\"]`\n                    // value is rewritten to a proper array schema), which would otherwise be lost.\n                    result.setAdditionalProperties(normalized);\n                }\n            }\n\n            return result;\n        } else if (schema instanceof BooleanSchema) {\n            normalizeBooleanSchema(schema, visitedSchemas);\n        } else if (schema instanceof IntegerSchema) {\n            normalizeIntegerSchema(schema, visitedSchemas);\n        } else if (schema instanceof Schema) {\n            return normalizeSimpleSchema(schema, visitedSchemas);\n        } else {\n            throw new RuntimeException(\"Unknown schema type found in normalizer: \" + schema);\n        }\n        return schema;\n    }\n\n    /**\n     * Normalize reference schema with allOf to support sibling properties\n     *\n     * @param schema         Schema\n     */\n    protected void normalizeReferenceSchema(Schema schema) {\n        if (schema.getType() != null || schema.getTypes() != null && !schema.getTypes().isEmpty()) {\n            // clears type(s) given that $ref is set\n            schema.setType(null);\n            schema.setTypes(null);\n            LOGGER.warn(\"Type(s) cleared (set to null) given $ref is set to {}.\", schema.get$ref());\n        }\n\n        if (schema.getTitle() != null || schema.getDescription() != null","sourceCodeStart":1049,"sourceCodeEnd":1085,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java#L1049-L1085","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\ncomponents:\n  schemas:\n    PetList:\n      type: array\n      items:        # null items -> unrecognizable schema node\n# after\ncomponents:\n  schemas:\n    PetList:\n      type: array\n      items:\n        $ref: '#/components/schemas/Pet'","handlingStrategy":"validation","validationCode":"// Reject null/empty schema nodes before normalization\nOpenAPI api = ...;\nMap<String, Schema> schemas = api.getComponents().getSchemas();\nschemas.forEach((name, s) -> {\n    if (s == null) throw new IllegalStateException(\"Null schema: \" + name);\n    if (s.getItems() == null && \"array\".equals(s.getType()))\n        throw new IllegalStateException(\"Array without items: \" + name);\n    if (s.get$ref() != null && s.get$ref().isEmpty())\n        throw new IllegalStateException(\"Empty $ref: \" + name);\n});","typeGuard":null,"tryCatchPattern":"try {\n    generator.opts(input).generate();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unknown schema type found in normalizer\")) {\n        // schema node was null/unrecognizable: audit spec for null schema keys (items:, additionalProperties: ~)\n        throw new GenerationFailure(\"Spec contains null/invalid schema node\", e);\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["openapi-generator","openapi","schema","normalizer","null-safety"],"backgroundTag":"malformed-openapi-schema","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}