OpenAPITools/openapi-generator · error · RuntimeException

Could not generate api file for '{tag}'

Error message

Could not generate api file for '{tag}'

What it means

DefaultGenerator.generateApis (line 693) iterates one tag at a time, processes its operations into an OperationsMap and writes the api source, api test and api doc files. Any exception inside that per-tag block - operation conversion, template data assembly, or file writing - is wrapped as RuntimeException with the tag name. Like errors [1]/[2] it is a wrapper: the real cause is the chained exception, and the tag tells you which group of operations to inspect.

Source

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

                            }
                        }
                    }
                }

                // to generate api documentation files
                for (String templateName : config.apiDocTemplateFiles().keySet()) {
                    String filename = config.apiDocFilename(templateName, tag);
                    File written = processTemplateToFile(operation, templateName, filename, generateApiDocumentation, CodegenConstants.API_DOCS);
                    if (written != null) {
                        files.add(written);
                        if (config.isEnablePostProcessFile() && !dryRun) {
                            config.postProcessFile(written, "api-doc");
                        }
                    }
                }

            } catch (Exception e) {
                throw new RuntimeException("Could not generate api file for '" + tag + "'", e);
            }
        }
        if (GlobalSettings.getProperty("debugOperations") != null) {
            LOGGER.info("############ Operation info ############");
            Json.prettyPrint(allOperations);
        }

    }

    void generateWebhooks(List<File> files, List<WebhooksMap> allWebhooks, List<ModelMap> allModels) {
        if (!generateWebhooks) {
            // TODO: Process these anyway and present info via dryRun?
            LOGGER.info("Skipping generation of Webhooks.");
            return;
        }
        Map<String, List<CodegenOperation>> webhooks = processWebhooks(this.openAPI.getWebhooks());
        Set<String> webhooksToGenerate = getPropertyAsSet(CodegenConstants.WEBHOOKS);
        if (webhooksToGenerate != null && !webhooksToGenerate.isEmpty()) {

View on GitHub (pinned to fcec517be3)

Solutions

1. Read the innermost 'Caused by:' to identify whether it is spec data (conversion NPE) or template/IO.
2. Open the spec at the operations carrying the failing tag; add missing operationId values, fix $ref targets, and declare any securitySchemes referenced by security requirements.
3. Run 'openapi-generator-cli validate -i spec.yaml' and fix all diagnostics before regenerating.
4. If the cause is a missing/unwritable file: restore all api templates in your --template-dir and verify output-folder permissions.
5. Reduce to a minimal spec containing just the failing tag's operations; if it still fails with a generator-internal stack frame, upgrade openapi-generator or file an issue with the minimal repro.

Example fix

# before
paths:
  /pets:
    get:
      summary: List pets
      responses: { '200': { description: ok } }
# after
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets
      responses: { '200': { description: ok } }

// Ensure every operation has an operationId before generating
OpenAPI api = ...; // parsed spec
api.getPaths().forEach((path, item) -> item.readOperations().forEach((method, op) -> {
    if (op.getOperationId() == null || op.getOperationId().isEmpty()) {
        throw new IllegalStateException("Missing operationId: " + method + " " + path);
    }
}));

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not generate api file")) {
        String tag = e.getMessage().split("'")[1];
        // re-run with only that tag emitted (--global-property apis) to isolate, inspect root cause
        throw new GenerationFailure("API tag failed: " + tag, e.getCause());
    }
    throw e;
}

When it happens

Trigger: Operations under the named tag whose conversion throws: missing operationId where the generator requires one, dangling $ref in parameters/requestBody/responses, security requirements referencing undefined securitySchemes, parameter names colliding after sanitization, unsupported content types; or template-side failures: missing api template in a --template-dir override, custom lambda throwing, unwritable output path for the api file.

Common situations: Specs exported from tools that omit operationId; specs split into multiple files where $ref targets a file that failed to resolve; renaming/moving tags so file names collide on case-insensitive filesystems; custom api templates not updated after a generator upgrade added new bundle keys.

Related errors

• Could not process model '{name}'.Please make sure that your
• Could not process operation: Tag: {tag} Operation: {oper
• Could not generate model '{modelName}'
• Could not generate supporting file '{support}'
• Unknown schema type found in normalizer: {schema}

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