What causes "Invalid mergeMode value '${mergeMode}'. Valid values are: REF, DEEP" in OpenAPITools/openapi-generator?

Set REF or DEEP (any casing works because the code uppercases it).

OpenAPITools/openapi-generator · error · MojoExecutionException

Invalid mergeMode value '${mergeMode}'. Valid values are: RE

Error message

Invalid mergeMode value '${mergeMode}'. Valid values are: REF, DEEP

What it means

Thrown by CodeGenMojo.execute when <inputSpecFiles> is used and MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT)) throws IllegalArgumentException — i.e. the configured mergeMode is not one of REF or DEEP (case-insensitive). The value is uppercased but not trimmed, so stray whitespace also fails. The catch converts it to a MojoExecutionException naming the valid values.

Source

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

    @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) {
                    throw new MojoExecutionException("Invalid mergeConflictStrategy value '" + mergeConflictStrategy
                            + "'. Valid values are: WARN, FAIL");
                }
            }

            inputSpec = builder.buildMergedSpec();

View on GitHub (pinned to fcec517be3)

Solutions

Set <mergeMode>REF</ref> or <mergeMode>DEEP</mergeMode> (any casing works because the code uppercases it).
Remove surrounding whitespace/newlines from the element value — the code does not trim.
If you do not need merging behavior control, remove <mergeMode> entirely so the plugin default applies.

Example fix

<!-- before -->
<mergeMode>ref_merge</mergeMode>

<!-- after -->
<mergeMode>REF</mergeMode>

Defensive patterns

Strategy: validation

Validate before calling

# CI pre-check: mergeMode, when present, must be REF or DEEP (case-insensitive)
MODE=$(mvn -q help:evaluate -Dexpression=mergeMode -DforceStdout 2>/dev/null)
if [ -n "$MODE" ] && ! echo "$MODE" | tr '[:lower:]' '[:upper:]' | grep -qx '\(REF\|DEEP\)'; then
  echo "invalid mergeMode: $MODE"; exit 1
fi

Prevention

Pin mergeMode to REF or DEEP in a shared parent POM; only override with those two values.
Remember the lookup uppercases but does not trim — keep the element value on one line with no padding.
Add a POM-lint step asserting enum-valued properties match the documented sets.

When it happens

Trigger: Setting <mergeMode>reference</mergeMode>, <mergeMode>deep_merge</mergeMode>, or <mergeMode> REF</mergeMode> (leading space) in the generate goal while using inputSpecFiles. A null mergeMode raises NullPointerException instead, so this specific message implies a non-null but unrecognized string.

Common situations: Copying mergeMode vocabulary from swagger-maven-plugin or other tools whose mode names differ; hand-editing the POM and introducing whitespace or a typo; documentation version drift where valid mode names changed between plugin releases.

Related errors

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