{"record":{"id":"75370931d830d274","repo":"OpenAPITools/openapi-generator","slug":"mergedfileoutputdir-must-be-set-when-inputspecfile","errorCode":null,"errorMessage":"mergedFileOutputDir must be set when inputSpecFiles is used","messagePattern":"mergedFileOutputDir must be set when inputSpecFiles is used","errorType":"exception","errorClass":"MojoExecutionException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java","lineNumber":626,"sourceCode":"    @Parameter(defaultValue = \"${mojoExecution}\", readonly = true)\n    private MojoExecution mojo;\n\n    /**\n     * The project being built.\n     */\n    @Parameter(readonly = true, required = true, defaultValue = \"${project}\")\n    private MavenProject project;\n\n    @Override\n    public void execute() throws MojoExecutionException {\n        if (StringUtils.isBlank(inputSpec) && StringUtils.isBlank(inputSpecRootDirectory) && (inputSpecFiles == null || inputSpecFiles.isEmpty())) {\n            LOGGER.error(\"inputSpec, inputSpecRootDirectory, or inputSpecFiles must be specified\");\n            throw new MojoExecutionException(\"inputSpec, inputSpecRootDirectory, or inputSpecFiles must be specified\");\n        }\n\n        if (inputSpecFiles != null && !inputSpecFiles.isEmpty()) {\n            if (mergedFileOutputDir == null) {\n                throw new MojoExecutionException(\"mergedFileOutputDir must be set when inputSpecFiles is used\");\n            }\n            MergedSpecBuilder.MergeMode resolvedMergeMode;\n            try {\n                resolvedMergeMode = MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT));\n            } catch (IllegalArgumentException e) {\n                throw new MojoExecutionException(\"Invalid mergeMode value '\" + mergeMode\n                        + \"'. Valid values are: REF, DEEP\");\n            }\n\n            MergedSpecBuilder builder = new MergedSpecBuilder(inputSpecFiles, mergedFileOutputDir.getAbsolutePath(),\n                    mergedFileName, mergedFileInfoName, mergedFileInfoDescription, mergedFileInfoVersion, auth)\n                    .withMergeMode(resolvedMergeMode);\n\n            if (resolvedMergeMode == MergedSpecBuilder.MergeMode.DEEP) {\n                try {\n                    builder.withConflictStrategy(\n                            MergedSpecBuilder.MergeConflictStrategy.valueOf(mergeConflictStrategy.toUpperCase(Locale.ROOT)));\n                } catch (IllegalArgumentException e) {","sourceCodeStart":608,"sourceCodeEnd":644,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java#L608-L644","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add <mergedFileOutputDir>${project.build.directory}/generated-openapi</mergedFileOutputDir> next to <inputSpecFiles> in the plugin configuration.","Prefer a path under ${project.build.directory} so the merged artifact is cleaned by mvn clean.","If you did not intend file-list merging, remove <inputSpecFiles> and use a single <inputSpec> instead."],"exampleFix":"<!-- before -->\n<configuration>\n  <inputSpecFiles>\n    <inputSpecFile>${project.basedir}/specs/users.yaml</inputSpecFile>\n  </inputSpecFiles>\n</configuration>\n\n<!-- after -->\n<configuration>\n  <inputSpecFiles>\n    <inputSpecFile>${project.basedir}/specs/users.yaml</inputSpecFile>\n  </inputSpecFiles>\n  <mergedFileOutputDir>${project.build.directory}/merged-spec</mergedFileOutputDir>\n</configuration>","handlingStrategy":"validation","validationCode":"# fail fast if inputSpecFiles is configured without mergedFileOutputDir\nxmllint --xpath \"//*[local-name()='inputSpecFiles']\" pom.xml >/dev/null 2>&1 && \\\n  ! xmllint --xpath \"//*[local-name()='mergedFileOutputDir']\" pom.xml >/dev/null 2>&1 && \\\n  { echo 'mergedFileOutputDir required when inputSpecFiles is used'; exit 1; }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat inputSpecFiles and mergedFileOutputDir as an inseparable pair in code review.","Point mergedFileOutputDir under ${project.build.directory} so clean removes stale merged specs.","Keep merge settings at plugin-level <configuration> so all executions (generate/validate) inherit both properties."],"tags":["openapi-generator","maven","plugin-config","spec-merging","missing-parameter"],"backgroundTag":"missing-required-config","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}