What causes "Code generation failed. See above for the full exception." in OpenAPITools/openapi-generator?

Rerun with mvn -e (the comment in the source notes Maven only shows plugin stack traces with -e) and read the first 'unexpected error in Open-API generation' / logged exception above this message — that is the real cause.

OpenAPITools/openapi-generator · error · MojoExecutionException

Code generation failed. See above for the full exception.

Error message

Code generation failed. See above for the full exception.

What it means

Catch-all wrapper at the end of CodeGenMojo's generation method: any Exception thrown by DefaultGenerator.opts(...).generate() or the checksum bookkeeping — invalid OpenAPI document, unsupported option for the chosen generator, missing template files, unwritable output, network failure fetching a remote spec — is logged via getLog().error(e) and rethrown as this MojoExecutionException. The message deliberately says 'see above' because the root cause is the logged exception, not this wrapper.

Source

Thrown at modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java:1144

            File storedInputSpecHashFile = getHashFile(inputSpecFile);
            if (storedInputSpecHashFile.getParent() != null && !new File(storedInputSpecHashFile.getParent()).exists()) {
                File parent = new File(storedInputSpecHashFile.getParent());
                if (!parent.mkdirs()) {
                    throw new RuntimeException("Failed to create the folder " + parent.getAbsolutePath() +
                            " to store the checksum of the input spec.");
                }
            }

            Files.asCharSink(storedInputSpecHashFile, StandardCharsets.UTF_8).write(calculateInputSpecHash(inputSpec));
        } catch (Exception e) {
            // Maven logs exceptions thrown by plugins only if invoked with -e
            // I find it annoying to jump through hoops to get basic diagnostic information,
            // so let's log it in any case:
            if (buildContext != null) {
                buildContext.addMessage(inputSpecFile, 0, 0, "unexpected error in Open-API generation", BuildContext.SEVERITY_WARNING, e);
            }
            getLog().error(e);
            throw new MojoExecutionException(
                    "Code generation failed. See above for the full exception.");
        }
    }

    /**
     * Calculate an SHA256 hash for the openapi specification.
     * If the specification is hosted on a remote resource it is downloaded first.
     *
     * @param inputSpec - Openapi specification input file. Can denote a URL or file path.
     * @return openapi specification hash
     */
    private String calculateInputSpecHash(String inputSpec) {
        final ParseOptions parseOptions = new ParseOptions();
        parseOptions.setResolve(true);

        final URL remoteUrl = inputSpecRemoteUrl();
        final List<AuthorizationValue> authorizationValues = AuthParser.parse(this.auth);

View on GitHub (pinned to fcec517be3)

Solutions

Rerun with mvn -e (the comment in the source notes Maven only shows plugin stack traces with -e) and read the first 'unexpected error in Open-API generation' / logged exception above this message — that is the real cause.
Validate the spec first: run the validate goal (openapi-generator:validate) or openapi-generator-cli validate on the same input.
Check generator-specific options against the generator's documentation (mvn ...:config-help or openapi-generator-cli config-help -g <name>).
If the cause is environmental (permissions, network for remote specs), fix that resource and rerun.

Defensive patterns

Strategy: try-catch

Validate before calling

# pre-flight the spec and options before the build
openapi-generator-cli validate -i src/main/resources/openapi.yaml
openapi-generator-cli config-help -g java | grep -i '<optionYouUse>'

Try / catch

# CI wrapper: run the goal, and on failure re-print the root cause section
mvn openapi-generator:generate -e || {
  grep -B2 -A40 'unexpected error in Open-API generation' build.log || true
  exit 1
}

Prevention

Always build with -e (or -X) when this plugin runs; the wrapper hides the cause otherwise.
Run the validate goal before generate in CI to catch spec issues with clearer messages.
Pin the plugin version and re-check configOptions after upgrades — most wrapped failures are rejected options or spec rules.
Treat 'Code generation failed' as a pointer, not a diagnosis: the real exception is logged just above.

When it happens

Trigger: Any downstream failure during generation: spec with invalid references (unresolved $ref), generator-specific configOptions rejected by the generator, missing/locked template files, output collision with existing read-only files, remote inputSpec URL unreachable, or the checksum RuntimeException from the same method.

Common situations: CI builds where the real stack trace scrolled past; upgrading the plugin and hitting changed option names; specs that pass YAML parsing but violate OpenAPI schema rules; generated-code directories checked into git as read-only.

Related errors

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