OpenAPITools/openapi-generator · error · RuntimeException

Could not process operation: Tag: {tag} Operation: {oper

Error message

Could not process operation:
  Tag: {tag}
  Operation: {operationId}
  Resource: {httpMethod} {resourcePath}
  Schemas: {schemas}
  Exception: {exception}

What it means

Inside operation processing (the loop converting each Operation into a CodegenOperation), any exception is wrapped with maximal context: the tag, operationId, HTTP method + resource path, the full components.schemas map, and the underlying exception's message. This is the diagnostic wrapper for per-operation conversion failures - use the structured lines to jump straight to the failing operation; the Exception line summarizes the root cause (see the chained exception for the full trace).

Source

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

                        codegenOperation.hasAuthMethods = true;
                    } else {
                        authMethods = getAuthMethods(globalSecurities, securitySchemes);

                        if (authMethods != null && !authMethods.isEmpty()) {
                            List<CodegenSecurity> fullAuthMethods = config.fromSecurity(authMethods);
                            codegenOperation.authMethods = filterAuthMethods(fullAuthMethods, globalSecurities);
                            codegenOperation.hasAuthMethods = true;
                        }
                    }
                }
            } catch (Exception ex) {
                String msg = "Could not process operation:\n" //
                        + "  Tag: " + tag + "\n"//
                        + "  Operation: " + operation.getOperationId() + "\n" //
                        + "  Resource: " + httpMethod + " " + resourcePath + "\n"//
                        + "  Schemas: " + openAPI.getComponents().getSchemas() + "\n"  //
                        + "  Exception: " + ex.getMessage();
                throw new RuntimeException(msg, ex);
            }
        }
    }

    private static String generateParameterId(Parameter parameter) {
        return null == parameter.get$ref() ? parameter.getName() + ":" + parameter.getIn() : parameter.get$ref();
    }

    private OperationsMap processOperations(CodegenConfig config, String tag, List<CodegenOperation> ops, List<ModelMap> allModels) {
        OperationsMap operations = new OperationsMap();
        OperationMap objs = new OperationMap();
        objs.setClassname(config.toApiName(tag));
        objs.setPathPrefix(config.toApiVarName(tag));

        // check for nickname uniqueness
        if (config.getAddSuffixToDuplicateOperationNicknames()) {
            Set<String> opIds = new HashSet<>();
            int counter = 0;

View on GitHub (pinned to fcec517be3)

Solutions

1. Use the 'Resource:' line to open the exact operation in the spec, and the 'Exception:' line for the root-cause summary; then read the chained stack trace.
2. Fix dangling references first - grep the spec for every $ref under that operation and confirm each target exists (parameters, requestBody, responses, security).
3. Run strict validation: 'openapi-generator-cli validate -i spec.yaml' and resolve all messages.
4. For security failures, declare the referenced scheme under components.securitySchemes or remove the security requirement.
5. If validation is clean and the trace is generator-internal, minimize to the single operation and upgrade openapi-generator or report with the minimal repro.

Example fix

# before
paths:
  /pets:
    get:
      operationId: listPets
      security: [{ petstoreAuth: [] }]   # scheme never declared
# after - declare the referenced scheme
components:
  securitySchemes:
    petstoreAuth:
      type: http
      scheme: bearer

// Pre-validate: every $ref and security requirement in every operation must resolve
OpenAPI api = ...;
Set<String> schemas = api.getComponents().getSchemas().keySet();
Set<String> secSchemes = api.getComponents().getSecuritySchemes() == null
        ? Set.of() : api.getComponents().getSecuritySchemes().keySet();
api.getPaths().forEach((p, item) -> item.readOperations().forEach((m, op) -> {
    if (op.getSecurity() != null) op.getSecurity().forEach(req -> req.keySet().stream()
            .filter(k -> !secSchemes.contains(k))
            .findAny().ifPresent(k -> { throw new IllegalStateException("Undefined securityScheme '" + k + "' on " + m + " " + p); }));
}));

try {
    generator.opts(input).generate();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not process operation:")) {
        // message lines carry Tag/Operation/Resource/Exception - parse and route to spec owners
        throw new GenerationFailure(extractField(e.getMessage(), "Resource"), e.getCause());
    }
    throw e;
}

When it happens

Trigger: An operation whose parameters/requestBody/responses contain dangling or malformed $refs; a security requirement naming a scheme absent from components.securitySchemes; parameters that collide after sanitization (duplicate names in the same operation); enum/null shapes hitting generator NPEs; deprecated constructs (body parameters converted from Swagger 2.0) failing conversion in newer generators.

Common situations: Multi-file specs where $ref points into a file that silently failed to resolve; specs edited to remove a schema/securityScheme while operations still reference it; Swagger 2.0 -> OpenAPI 3 conversions leaving artifacts; generator upgrades tightening previously-tolerated shapes.

Related errors

• Could not process model '{name}'.Please make sure that your
• Could not generate api file for '{tag}'
• 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}

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