OpenAPITools/openapi-generator · error · RuntimeException

schema cannot be null with ref {ref}

Error message

schema cannot be null with ref {ref}

What it means

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.

Source

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

            return;
        }

        if (schema.getAllOf().size() == 1) {
            return;
        }

        for (Object item : schema.getAllOf()) {
            if (!(item instanceof Schema)) {
                throw new RuntimeException("Error! allOf schema is not of the type Schema: " + item);
            }
            Schema s = (Schema) item;

            if (StringUtils.isNotEmpty(s.get$ref())) {
                String ref = ModelUtils.getSimpleRef(s.get$ref());
                // TODO need to check for requestBodies?
                Schema refSchema = openAPI.getComponents().getSchemas().get(ref);
                if (refSchema == null) {
                    throw new RuntimeException("schema cannot be null with ref " + ref);
                }
                if (refSchema.getExtensions() == null) {
                    refSchema.setExtensions(new HashMap<>());
                }

                if (refSchema.getExtensions().containsKey(X_PARENT)) {
                    // doing nothing as x-parent already exists
                } else {
                    refSchema.getExtensions().put(X_PARENT, true);
                }

                LOGGER.debug("processUseAllOfRefAsParent added `x-parent: true` to {}", refSchema);
            }
        }
    }

    /**
     * Remove/hide the x-internal in operations and model.

View on GitHub (pinned to fcec517be3)

Solutions

1. Check the ref printed in the message and add/rename the schema in components/schemas so the name matches exactly (case-sensitive).
2. Bundle multi-file specs first (swagger-cli bundle or resolveFully with the parser) so external refs become local #/components/schemas refs.
3. If the ref intentionally targets a requestBody or non-schema component, remove the REF_AS_PARENT_IN_ALLOF rule or restructure the allOf.
4. Lint for dangling refs (spectral oas3-valid-schema-example / unresolved-reference rules) in CI.

Example fix

# before
allOf:
  - $ref: '#/components/schemas/Animl'
# after (match the defined schema name)
allOf:
  - $ref: '#/components/schemas/Animal'

// Verify every allOf $ref resolves into components/schemas before generation
Set<String> defined = spec.getComponents().getSchemas().keySet();
for (Schema s : spec.getComponents().getSchemas().values()) {
    if (s.getAllOf() == null) continue;
    for (Object item : s.getAllOf()) {
        Schema child = (Schema) item;
        String ref = child.get$ref();
        if (ref != null && ref.startsWith("#/components/schemas/")
                && !defined.contains(ref.substring("#/components/schemas/".length()))) {
            throw new IllegalArgumentException("Dangling allOf ref: " + ref);
        }
    }
}

catch RuntimeException with message containing "schema cannot be null with ref" — report the ref name; treat as a spec defect, not transient.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown schema type found in normalizer: {schema}
• Error! allOf schema is not of the type Schema: {item}
• Error! oneOf schema is not of the type Schema: {item}
• Error! anyOf schema is not of the type Schema: {item}
• %s Input: `%s`. Error: %s

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