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

Set REF or DEEP ; lowercase works because the code uppercases the value.

OpenAPITools/openapi-generator · error · MojoExecutionException

Invalid mergeMode value '" + mergeMode + "'. Valid values ar

Error message

Invalid mergeMode value '" + mergeMode + "'. Valid values are: REF, DEEP

What it means

Thrown in ValidateMojo.mergeInDirectory when inputSpecFiles is used and MergedSpecBuilder.MergeMode.valueOf(mergeMode.toUpperCase(Locale.ROOT)) throws IllegalArgumentException — the <mergeMode> value is neither REF nor DEEP (case-insensitive, whitespace not trimmed). The validate goal mirrors the generate goal's file-list branch, so the same value rules apply.

Source

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

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

      String mergedSpec = builder.buildMergedSpec();

View on GitHub (pinned to fcec517be3)

Solutions

Set <mergeMode>REF</mergeMode> or <mergeMode>DEEP</mergeMode>; lowercase works because the code uppercases the value.
Remove leading/trailing whitespace or line breaks from the element text.
Centralize mergeMode in plugin-level configuration so validate and generate cannot drift apart.

Example fix

<!-- before -->
<mergeMode>combine</mergeMode>

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

Defensive patterns

Strategy: validation

Validate before calling

MODE=$(mvn -q help:evaluate -Dexpression=mergeMode -DforceStdout 2>/dev/null)
if [ -n "$MODE" ] && ! echo "$MODE" | tr -d '[:space:]' | tr '[:lower:]' '[:upper:]' | grep -qx '\(REF\|DEEP\)'; then
  echo "invalid mergeMode: '$MODE'"; exit 1
fi

Prevention

Allow only REF/DEEP values in review for the validate goal too — it duplicates the generate goal's parsing.
Keep the element on one line; whitespace inside the value is not trimmed.
Prefer plugin-level configuration over per-execution copies to avoid divergence.

When it happens

Trigger: Validate goal configured with <inputSpecFiles> and <mergeMode>ALL</mergeMode>, <mergeMode>ref,deep</mergeMode>, or a whitespace-padded value. Null mergeMode produces NullPointerException rather than this message.

Common situations: POMs where generate was configured correctly but validate got a hand-written copy with a typo; vocabulary borrowed from other merge tools (swagger-maven-plugin, speccy); XML formatters injecting indentation whitespace into the value.

Related errors

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