OpenAPITools/openapi-generator · error · RuntimeException

Could not process model

Error message

Could not process model '{name}'.Please make sure that your schema is correct!

What it means

DefaultGenerator.generate() loops over every entry in components/schemas, builds a single-entry map and runs processModels(config, schemaMap) plus model-name mapping and additionalProperties merging. ANY exception raised while converting that schema into a Codegen model (naming, type resolution, property processing, post-processing) is caught and rethrown as this RuntimeException with the offending model name. It is a pure wrapper: the real failure is always the chained 'Caused by' exception, and the model named in the message is the one to inspect in your spec.

Solutions

1. Read the full stack trace to the innermost 'Caused by:' - that names the actual defect (e.g. NullPointerException in fromProperty, ambiguous parent resolution) and the fix targets it, not this wrapper.
2. Validate the spec before generating: 'openapi-generator-cli validate -i spec.yaml' or the online editor; fix every reported dangling reference or malformed node.
3. Extract the model named in the message into a minimal one-schema spec and reproduce; this isolates whether the defect is the schema itself or its interaction with others.
4. If the root cause is naming (reserved word, leading digit, special characters), rename the schema/property in the spec or remap it with the generator's model-name/property-name options (e.g. --additional-properties modelNamePrefix/ modelMappings) instead of fighting the sanitizer.
5. If the stack trace points inside the generator (no obvious spec defect), upgrade to the latest openapi-generator - model-processing bugs on edge-case schemas are patched frequently.

Example fix

# before (components/schemas)
Pet:
  properties:
    category:
      $ref: '#/components/schemas/Categories'   # typo: schema is 'Category'
# after
Pet:
  properties:
    category:
      $ref: '#/components/schemas/Category'

// Validate the spec (including reference resolution) before generating
io.swagger.v3.parser.OpenAPIParser parser = new io.swagger.v3.parser.OpenAPIParser();
io.swagger.v3.parser.core.models.SwaggerParseResult result =
        parser.readLocation("api.yaml", null, null);
if (result.getOpenAPI() == null || !result.getMessages().isEmpty()) {
    throw new IllegalArgumentException("Invalid spec: " + result.getMessages());
}

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not process model")) {
        String modelName = e.getMessage().split("'")[1]; // extract failing model
        // surface modelName + root cause to the user, keep the chain
        throw new GenerationFailure("Spec model failed: " + modelName, e.getCause());
    }
    throw e;
}

When it happens

Trigger: A components/schemas entry whose processing throws: dangling $ref (referenced schema missing), a schema/property name that the generator's sanitizer turns into an invalid or colliding identifier, an enum with null/empty values, additionalProperties or items nodes that are malformed, unsupported 'type'+'format' combinations hitting a generator NPE, or circular/nested allOf that breaks parent resolution. The spec parsed leniently (SwaggerParser does not fully validate) but fails during model conversion.

Common situations: Hand-edited YAML with a typo in a $ref path ('#/components/schemas/Categories' vs 'Category'); specs exported from Postman/Stoplight or another codegen tool producing empty 'type: object' nodes with odd defaults; schema names starting with a digit or containing characters the target language rejects; upgrading openapi-generator and hitting changed naming rules; inline schemas that worked in 3.0 but regress in a newer minor release.

Related errors

• Could not process operation: Tag
• Could not generate api file for
• Could not generate model
• Error! allOf schema is not of the type Schema
• Error! anyOf schema is not of the type Schema

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

Appendix: source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultGenerator.java:530

                        LOGGER.info("Model {} not generated since it's an alias to map (without property) and `generateAliasAsModel` is set to false (default)", name);
                        continue;
                    }
                } else if (ModelUtils.isArraySchema(schema)) { // check to see if it's an "array" model
                    if (!ModelUtils.shouldGenerateArrayModel(schema)) {
                        // schema without property, i.e. alias to array
                        LOGGER.info("Model {} not generated since it's an alias to array (without property) and `generateAliasAsModel` is set to false (default)", name);
                        continue;
                    }
                }

                Map<String, Schema> schemaMap = new HashMap<>();
                schemaMap.put(name, schema);
                ModelsMap models = processModels(config, schemaMap);
                models.put("classname", config.toModelName(name));
                models.putAll(config.additionalProperties());
                allProcessedModels.put(name, models);
            } catch (Exception e) {
                throw new RuntimeException("Could not process model '" + name + "'" + ".Please make sure that your schema is correct!", e);
            }
        }

        // loop through all models to update children models, isSelfReference, isCircularReference, etc
        allProcessedModels = config.updateAllModels(allProcessedModels);

        // post process all processed models
        allProcessedModels = config.postProcessAllModels(allProcessedModels);

        if (generateRecursiveDependentModels) {
            for (ModelsMap modelsMap : allProcessedModels.values()) {
                for (ModelMap mm : modelsMap.getModels()) {
                    CodegenModel cm = mm.getModel();
                    if (cm != null) {
                        for (CodegenProperty variable : cm.getVars()) {
                            generateModelsForVariable(files, allModels, unusedModels, aliasModels, processedModels, variable);
                        }
                        //TODO:  handle interfaces

View on GitHub (pinned to fcec517be3)