{"record":{"id":"35fc165747922027","repo":"OpenAPITools/openapi-generator","slug":"schema-cannot-be-null-with-ref-ref","errorCode":null,"errorMessage":"schema cannot be null with ref {ref}","messagePattern":"schema cannot be null with ref (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java","lineNumber":1426,"sourceCode":"            return;\n        }\n\n        if (schema.getAllOf().size() == 1) {\n            return;\n        }\n\n        for (Object item : schema.getAllOf()) {\n            if (!(item instanceof Schema)) {\n                throw new RuntimeException(\"Error! allOf schema is not of the type Schema: \" + item);\n            }\n            Schema s = (Schema) item;\n\n            if (StringUtils.isNotEmpty(s.get$ref())) {\n                String ref = ModelUtils.getSimpleRef(s.get$ref());\n                // TODO need to check for requestBodies?\n                Schema refSchema = openAPI.getComponents().getSchemas().get(ref);\n                if (refSchema == null) {\n                    throw new RuntimeException(\"schema cannot be null with ref \" + ref);\n                }\n                if (refSchema.getExtensions() == null) {\n                    refSchema.setExtensions(new HashMap<>());\n                }\n\n                if (refSchema.getExtensions().containsKey(X_PARENT)) {\n                    // doing nothing as x-parent already exists\n                } else {\n                    refSchema.getExtensions().put(X_PARENT, true);\n                }\n\n                LOGGER.debug(\"processUseAllOfRefAsParent added `x-parent: true` to {}\", refSchema);\n            }\n        }\n    }\n\n    /**\n     * Remove/hide the x-internal in operations and model.","sourceCodeStart":1408,"sourceCodeEnd":1444,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java#L1408-L1444","documentation":"Thrown by the REF_AS_PARENT_IN_ALLOF normalizer rule when an allOf child is a $ref but openAPI.getComponents().getSchemas().get(ref) returns null — i.e. the referenced schema name is not present in components/schemas. The code deliberately does not resolve requestBodies or other component sections (see the TODO in the source), so the ref must point at a schema defined in the same document. It is a hard failure, not a skip, because the rule needs to write x-parent: true onto the target.","triggerScenarios":"REF_AS_PARENT_IN_ALLOF enabled plus an allOf child like {$ref: '#/components/schemas/Missing'} where 'Missing' is absent from components/schemas. Also fires for refs to external files or to #/components/requestBodies/... which this rule never looks up.","commonSituations":"Typos or case mismatches in ref names ('User' vs 'user'); specs split across files where external $refs were not bundled/inlined before generation; refs to non-schema components; renaming a schema in an editor without updating dependents.","solutions":["Check the ref printed in the message and add/rename the schema in components/schemas so the name matches exactly (case-sensitive).","Bundle multi-file specs first (swagger-cli bundle or resolveFully with the parser) so external refs become local #/components/schemas refs.","If the ref intentionally targets a requestBody or non-schema component, remove the REF_AS_PARENT_IN_ALLOF rule or restructure the allOf.","Lint for dangling refs (spectral oas3-valid-schema-example / unresolved-reference rules) in CI."],"exampleFix":"# before\nallOf:\n  - $ref: '#/components/schemas/Animl'\n# after (match the defined schema name)\nallOf:\n  - $ref: '#/components/schemas/Animal'","handlingStrategy":"validation","validationCode":"// Verify every allOf $ref resolves into components/schemas before generation\nSet<String> defined = spec.getComponents().getSchemas().keySet();\nfor (Schema s : spec.getComponents().getSchemas().values()) {\n    if (s.getAllOf() == null) continue;\n    for (Object item : s.getAllOf()) {\n        Schema child = (Schema) item;\n        String ref = child.get$ref();\n        if (ref != null && ref.startsWith(\"#/components/schemas/\")\n                && !defined.contains(ref.substring(\"#/components/schemas/\".length()))) {\n            throw new IllegalArgumentException(\"Dangling allOf ref: \" + ref);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"catch RuntimeException with message containing \"schema cannot be null with ref\" — report the ref name; treat as a spec defect, not transient.","preventionTips":["Bundle multi-file specs (swagger-cli bundle) so external refs become local before generating.","Use case-consistent schema names; avoid renaming schemas without a reference sweep.","Enable an unresolved-reference lint rule in CI."],"tags":["openapi","unresolved-ref","all-of","components","normalizer"],"backgroundTag":"unresolved-schema-reference","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}