OpenAPITools/openapi-generator · error · MojoExecutionException

inputSpec, inputSpecRootDirectory, or inputSpecFiles must be

Error message

inputSpec, inputSpecRootDirectory, or inputSpecFiles must be specified

What it means

Thrown by the generate goal (CodeGenMojo.execute) of openapi-generator-maven-plugin when none of the three mutually alternative spec inputs is configured: inputSpec (single file/URL), inputSpecRootDirectory (directory scan), or inputSpecFiles (explicit list). It is the first guard in execute(), so the goal fails immediately with a MojoExecutionException before any spec parsing or generation.

Source

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

     * Maven ProjectHelper used to manage build artifacts.
     */
    @Component
    MavenProjectHelper mavenProjectHelper;

    @Parameter(defaultValue = "${mojoExecution}", readonly = true)
    private MojoExecution mojo;

    /**
     * The project being built.
     */
    @Parameter(readonly = true, required = true, defaultValue = "${project}")
    private MavenProject project;

    @Override
    public void execute() throws MojoExecutionException {
        if (StringUtils.isBlank(inputSpec) && StringUtils.isBlank(inputSpecRootDirectory) && (inputSpecFiles == null || inputSpecFiles.isEmpty())) {
            LOGGER.error("inputSpec, inputSpecRootDirectory, or inputSpecFiles must be specified");
            throw new MojoExecutionException("inputSpec, inputSpecRootDirectory, or inputSpecFiles must be specified");
        }

        if (inputSpecFiles != null && !inputSpecFiles.isEmpty()) {
            if (mergedFileOutputDir == null) {
                throw new MojoExecutionException("mergedFileOutputDir must be set when inputSpecFiles is used");
            }
            MergedSpecBuilder.MergeMode resolvedMergeMode;
            try {
                resolvedMergeMode = MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT));
            } catch (IllegalArgumentException e) {
                throw new MojoExecutionException("Invalid mergeMode value '" + mergeMode
                        + "'. Valid values are: REF, DEEP");
            }

            MergedSpecBuilder builder = new MergedSpecBuilder(inputSpecFiles, mergedFileOutputDir.getAbsolutePath(),
                    mergedFileName, mergedFileInfoName, mergedFileInfoDescription, mergedFileInfoVersion, auth)
                    .withMergeMode(resolvedMergeMode);

View on GitHub (pinned to fcec517be3)

Solutions

Add <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec> to the plugin <configuration> for the generate goal.
If you have many spec files in a tree, use <inputSpecRootDirectory> instead — the plugin merges them via MergedSpecBuilder.
For an explicit list, use <inputSpecFiles> together with <mergedFileOutputDir>.
Verify the property names and that the configuration is attached to the openapi-generator:generate goal execution, not only to pluginManagement; run mvn help:describe or -X to confirm bound values.

Example fix

<!-- before -->
<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <executions><execution><goals><goal>generate</goal></goals></execution></executions>
</plugin>

<!-- after -->
<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <executions><execution><goals><goal>generate</goal></goals></execution></executions>
  <configuration>
    <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
    <generatorName>java</generatorName>
  </configuration>
</plugin>

Defensive patterns

Strategy: validation

Validate before calling

<!-- fail the build early with a clear message instead of letting the mojo fail -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <executions><execution>
    <id>check-spec-input</id>
    <goals><goal>enforce</goal></goals>
    <configuration><rules>
      <requireProperty>
        <property>openapi.spec.input</property>
        <message>Set -Dopenapi.spec.input or configure inputSpec for openapi-generator:generate</message>
      </requireProperty>
    </rules></configuration>
  </execution></executions>
</plugin>

Try / catch

# CI script: verify config before invoking the goal
mvn -q help:evaluate -Dexpression=inputSpec -DforceStdout | grep -q . \
  || { echo 'inputSpec missing in openapi-generator config'; exit 1; }

Prevention

Keep a checked-in, fully populated <configuration> block for the generate goal; do not rely on CLI -D flags in CI.
Fail fast in CI with a lint step that greps the POM for inputSpec/inputSpecRootDirectory/inputSpecFiles on every openapi-generator execution.
Use ${project.basedir}-relative paths so the build works from any module directory.
After any POM refactor, run the goal once locally before pushing.

When it happens

Trigger: Running mvn openapi-generator:generate (or the goal bound in the POM) with a <configuration> block that omits all three properties, or CLI invocation without -DinputSpec=... . Also happens when the configuration sits on the wrong execution/goal, or property names are typo'd (<inputspec> instead of <inputSpec>), so Maven never binds the value.

Common situations: Copy-pasted plugin snippet from docs with the spec path placeholder never filled in; spec path moved/renamed but the property deleted instead of updated; CI pipeline where the -DinputSpec flag was dropped from the mvn command; multi-module POM where the configuration was added to pluginManagement instead of the actual plugin execution.

Related errors

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