OpenAPITools/openapi-generator · error · RuntimeException

Issues with the OpenAPI input. Possible causes: invalid/miss

Error message

Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.

What it means

DefaultGenerator.generate() starts with a null guard on the parsed OpenAPI document. openAPI is populated during opts(...) from the input spec (ClientOptInput/GeneratorSettings flow and CodegenConfigurator); if generate() is reached with openAPI still null, nothing was ever parsed/attached and the run aborts immediately. This is an API-misuse guard that the CLI normally makes unreachable - it chiefly bites programmatic callers who skip or mis-order the setup steps.

Source

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

            if (ProcessUtils.hasHttpSignatureMethods(authMethods)) {
                bundle.put("hasHttpSignatureMethods", true);
                bundle.put("httpSignatureMethods", ProcessUtils.getHttpSignatureMethods(authMethods));
            }
            if (ProcessUtils.hasHttpBasicMethods(authMethods)) {
                bundle.put("hasHttpBasicMethods", true);
                bundle.put("httpBasicMethods", ProcessUtils.getHttpBasicMethods(authMethods));
            }
            if (ProcessUtils.hasApiKeyMethods(authMethods)) {
                bundle.put("hasApiKeyMethods", true);
                bundle.put("apiKeyMethods", ProcessUtils.getApiKeyMethods(authMethods));
            }
        }
    }

    @Override
    public List<File> generate() {
        if (openAPI == null) {
            throw new RuntimeException("Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.");
        }

        if (config == null) {
            throw new RuntimeException("missing config!");
        }

        if (config.getGeneratorMetadata() == null) {
            LOGGER.warn("Generator '{}' is missing generator metadata!", config.getName());
        } else {
            GeneratorMetadata generatorMetadata = config.getGeneratorMetadata();
            if (StringUtils.isNotEmpty(generatorMetadata.getGenerationMessage())) {
                LOGGER.info(generatorMetadata.getGenerationMessage());
            }

            Stability stability = generatorMetadata.getStability();
            String stabilityMessage = String.format(Locale.ROOT, "Generator '%s' is considered %s.", config.getName(), stability.value());
            if (stability == Stability.DEPRECATED) {
                LOGGER.warn(stabilityMessage);

View on GitHub (pinned to fcec517be3)

Solutions

Always build opts through org.openapitools.codegen.config.CodegenConfigurator: configurator.setInputSpec(...)/setGeneratorName(...) then ClientOptInput input = configurator.toClientOptInput(); generator.opts(input).generate().
If constructing ClientOptInput by hand, set the parsed spec on it (input.setOpenAPI(parsed) / via GeneratorSettings) before opts().
Before generate(), assert the pipeline is complete - parse the spec first (OpenAPIParser) and fail loudly if parsing produced null, so this guard never fires.
On the CLI, always pass -i <spec> (and verify the path exists) so the input is loaded.

Example fix

// before
DefaultGenerator generator = new DefaultGenerator();
generator.generate(); // RuntimeException: no OpenAPI attached
// after
CodegenConfigurator configurator = new CodegenConfigurator();
configurator.setInputSpec("api.yaml");
configurator.setGeneratorName("java");
ClientOptInput input = configurator.toClientOptInput();
new DefaultGenerator().opts(input).generate();

Defensive patterns

Strategy: validation

Validate before calling

// Parse and attach the spec explicitly; fail before generate()
io.swagger.v3.parser.core.models.SwaggerParseResult parsed =
        new io.swagger.v3.parser.OpenAPIParser().readLocation(specPath, null, null);
if (parsed.getOpenAPI() == null) {
    throw new IllegalArgumentException("Unparseable spec " + specPath + ": " + parsed.getMessages());
}
ClientOptInput input = new ClientOptInput();
input.setOpenAPI(parsed.getOpenAPI());
input.setConfig(CodegenConfigLoader.forName(generatorName));
new DefaultGenerator().opts(input).generate();

Try / catch

try {
    new DefaultGenerator().opts(input).generate();
} catch (RuntimeException e) {
    if ("Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.".equals(e.getMessage())) {
        // setup bug: spec never attached. Re-run the parse+opts pipeline; do NOT retry generate() as-is.
        throw new IllegalStateException("generate() called before opts() with a parsed spec", e);
    }
    throw e;
}

Prevention

Always construct opts via CodegenConfigurator.toClientOptInput() instead of hand-building ClientOptInput.
Fail fast on parse errors - never continue to generate() after a swallowed parse failure.
Wrap generation in a helper method that enforces spec-then-opts-then-generate ordering.

When it happens

Trigger: Calling new DefaultGenerator().generate() without first calling opts(...); building ClientOptInput manually and leaving the OpenAPI/spec unset (e.g. only setting generatorName); a wrapper that catches and swallows an earlier parse failure and then calls generate() anyway; migrating from an older API where setInputSpec was invoked directly on ClientOptInput.

Common situations: Service code that generates on demand and takes an error path that skips opts(); tutorials copied from an incompatible openapi-generator version; tests constructing DefaultGenerator directly without CodegenConfigurator.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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