OpenAPITools/openapi-generator · error · RuntimeException

Could not process model '{name}'.Please make sure that your

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.

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)

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: {tag} Operation: {oper
• Could not generate model '{modelName}'
• Could not generate api file for '{tag}'
• Unknown schema type found in normalizer: {schema}
• Error! allOf schema is not of the type Schema: {item}

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