OpenAPITools/openapi-generator · error · RuntimeException

Error! oneOf schema is not of the type Schema: {item}

Error message

Error! oneOf schema is not of the type Schema: {item}

What it means

normalizeOneOf loops schema.getOneOf() after the simplify-oneOf rules have run; it skips null entries but requires every remaining element to be an instanceof Schema before normalizing it in place. A non-Schema element - scalar, boolean schema, or raw object placed under oneOf - aborts normalization with this error showing the offending item. oneOf is the composition keyword most often populated by hand (polymorphism), which is exactly where malformed entries slip in.

Source

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

        // Remove duplicate oneOf entries
        ModelUtils.deduplicateOneOfSchema(schema);

        schema = processSimplifyOneOfEnum(schema);

        // simplify first as the schema may no longer be a oneOf after processing the rule below
        schema = processSimplifyOneOf(schema);

        // if it's still a oneOf, loop through the sub-schemas
        if (schema.getOneOf() != null) {
            for (int i = 0; i < schema.getOneOf().size(); i++) {
                // normalize oneOf sub schemas one by one
                Object item = schema.getOneOf().get(i);

                if (item == null) {
                    continue;
                }
                if (!(item instanceof Schema)) {
                    throw new RuntimeException("Error! oneOf schema is not of the type Schema: " + item);
                }

                // update sub-schema with the updated schema
                schema.getOneOf().set(i, normalizeSchema((Schema) item, visitedSchemas));
            }
            schema = processReplaceOneOfByMapping(schema);
        } else {
            // normalize it as it's no longer an oneOf
            schema = normalizeSchema(schema, visitedSchemas);
        }

        return schema;
    }

    protected Schema normalizeAnyOf(Schema schema, Set<Schema> visitedSchemas) {
        //transform anyOf into enums if needed
        schema = processSimplifyAnyOfEnum(schema);
        if (schema.getAnyOf() == null) {

View on GitHub (pinned to fcec517be3)

Solutions

1. Use the printed item to find the bad oneOf entry; replace it with a schema object or '$ref: ...'.
2. Remove boolean-schema members (true/false) from oneOf - not valid in OpenAPI 3.x.
3. Check every $ref under oneOf resolves to '#/components/schemas/...' exactly.
4. When building models in code, add Schema instances only, never Maps/scalars/nulls.
5. Validate the spec with a strict OpenAPI validator to catch composition member types pre-generation.

Example fix

# before
Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - true
# after
Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'

// Assert oneOf members are Schema instances and refs resolve
for (Schema s : api.getComponents().getSchemas().values()) {
    if (s.getOneOf() != null) {
        for (Object m : s.getOneOf()) {
            if (m == null) continue;
            if (!(m instanceof Schema)) {
                throw new IllegalStateException("Invalid oneOf member: " + m);
            }
            String ref = ((Schema) m).get$ref();
            if (ref != null && api.getComponents().getSchemas().get(ref.replace("#/components/schemas/", "")) == null) {
                throw new IllegalStateException("Dangling oneOf ref: " + ref);
            }
        }
    }
}

private static boolean oneOfMembersAreSchemas(Schema s) {
    return s.getOneOf() == null || s.getOneOf().stream()
            .allMatch(m -> m == null || m instanceof Schema);
}

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("oneOf schema is not of the type Schema")) {
        // message prints the member; fix the oneOf list (no booleans/scalars)
        throw new GenerationFailure("Invalid oneOf member", e);
    }
    throw e;
}

When it happens

Trigger: Polymorphic schemas hand-written with a stray scalar or boolean under oneOf ('- true' carried over from JSON Schema semantics); $ref typos that fail to deserialize into a Schema; programmatically built oneOf lists containing Maps or Strings; YAML indentation putting a plain value under oneOf.

Common situations: Hand-maintained discriminator/oneOf hierarchies; JSON Schema -> OpenAPI conversions; multi-file merges concatenating lists with separators that become scalars.

Related errors

• Unknown schema type found in normalizer: {schema}
• Error! allOf schema is not of the type Schema: {item}
• Error! anyOf schema is not of the type Schema: {item}
• Could not process model '{name}'.Please make sure that your
• Could not process operation: Tag: {tag} Operation: {oper

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