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

Thrown by CodeGenMojo.execute when the <inputSpecFiles> list is non-empty but <mergedFileOutputDir> is not set. Because merging an explicit file list materializes a merged spec file on disk, the plugin requires a directory to write it to and refuses to guess. It fails before any merge attempt, with a MojoExecutionException.

Source

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

    @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);

            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}/generated-openapi</mergedFileOutputDir> next to <inputSpecFiles> in the plugin configuration.
2. Prefer a path under ${project.build.directory} so the merged artifact is cleaned by mvn clean.
3. If you did not intend file-list merging, remove <inputSpecFiles> and use a single <inputSpec> instead.

Example fix

<!-- before -->
<configuration>
  <inputSpecFiles>
    <inputSpecFile>${project.basedir}/specs/users.yaml</inputSpecFile>
  </inputSpecFiles>
</configuration>

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

# fail fast if inputSpecFiles is configured without mergedFileOutputDir
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><inputSpecFile>a.yaml</inputSpecFile></inputSpecFiles> in the generate goal without a sibling <mergedFileOutputDir> element. Also occurs when migrating from inputSpecRootDirectory (which does not need the directory) to the explicit-list mode and forgetting the new required property.

Common situations: Teams splitting a monolithic OpenAPI file into per-domain files and adopting the file-list merge feature; POM refactors where the merge output directory was only configured in one profile; copying a snippet from documentation of a different plugin version that predates the requirement.

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/75370931d830d274. Report an issue: GitHub.