OpenAPITools/openapi-generator · error · MojoExecutionException

mergedFileOutputDir must be set when inputSpecFiles is used

Error message

mergedFileOutputDir must be set when inputSpecFiles is used

What it means

ValidateMojo.mergeInDirectory throws this when the explicit-file-list mode is chosen (inputSpecFiles non-empty) but mergedFileOutputDir is null. The merged spec must be written somewhere before it can be validated, so the plugin requires the directory and fails with a MojoExecutionException before attempting any merge.

Source

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

    if (isInputSpecEmpty && 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");
    }
  }

  private boolean shouldWeSkip() {
    if (Boolean.TRUE.equals(skip) || Boolean.TRUE.equals(skipValidateSpec)) {
      getLog().info("Validation is skipped.");
      return true;
    }
    return false;
  }

  private Optional<String> mergeInDirectory() throws MojoExecutionException {
    // Explicit file list takes precedence
    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);

      if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP) {
        try {
          builder.withConflictStrategy(
              MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.toUpperCase(Locale.ROOT)));
        } catch (IllegalArgumentException e) {

View on GitHub (pinned to fcec517be3)

Solutions

1. Add <mergedFileOutputDir>${project.build.directory}/merged-spec</mergedFileOutputDir> alongside <inputSpecFiles> in the validate execution.
2. Keep generate and validate merge settings in sync by placing them in the plugin-level <configuration> so both executions inherit them.
3. If file-list merging is not wanted for validation, point <inputSpec> at the already-merged file instead.

Example fix

<!-- before -->
<configuration>
  <inputSpecFiles>
    <inputSpecFile>specs/core.yaml</inputSpecFile>
  </inputSpecFiles>
</configuration>

<!-- after -->
<configuration>
  <inputSpecFiles>
    <inputSpecFile>specs/core.yaml</inputSpecFile>
  </inputSpecFiles>
  <mergedFileOutputDir>${project.build.directory}/merged-spec</mergedFileOutputDir>
</configuration>

# inputSpecFiles without mergedFileOutputDir -> fail before Maven does
xmllint --xpath "//*[local-name()='inputSpecFiles']" pom.xml >/dev/null 2>&1 && \
  ! xmllint --xpath "//*[local-name()='mergedFileOutputDir']" pom.xml >/dev/null 2>&1 && \
  { echo 'mergedFileOutputDir required when inputSpecFiles is used'; exit 1; }

When it happens

Trigger: Configuring <inputSpecFiles> for the validate goal without a sibling <mergedFileOutputDir>; or configuring the directory only on the generate execution and expecting the validate execution to inherit it (per-execution configuration does not merge that way).

Common situations: Splitting specs into per-domain files and wiring validation for the merged result; POM refactors that moved merge settings into a profile not active during validation.

Related errors

• mergedFileOutputDir must be set when inputSpecFiles is used
• inputSpec, inputSpecRootDirectory, or inputSpecFiles must be
• Invalid mergeMode value '${mergeMode}'. Valid values are: RE
• Invalid mergeConflictStrategy value '${mergeConflictStrategy
• The generator requires 'generatorName'. Refer to documentati

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