apache/beam · error · IllegalArgumentException

Unrecognized value for stable unique names:

Error message

Unrecognized value for stable unique names: 

What it means

Pipeline.validate() switches over options.getStableUniqueNames() (an enum with values like OFF, WARNING, ERROR). Any value outside the handled cases — including null or a corrupted/unrecognized setting — reaches the default branch and throws this IllegalArgumentException.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/Pipeline.java:635

        case WARNING:
          LOG.warn(
              "The following transforms do not have stable unique names: {}",
              Joiner.on(", ").join(transform(errors, new KeysExtractor())));
          break;
        case ERROR: // be very verbose here since it will just fail the execution
          throw new IllegalStateException(
              String.format(
                      "Pipeline update will not be possible because the following transforms do"
                          + " not have stable unique names: %s.",
                      Joiner.on(", ").join(transform(errors, new KeysExtractor())))
                  + "\n\n"
                  + "Conflicting instances:\n"
                  + Joiner.on("\n")
                      .join(transform(errors, new UnstableNameToMessage(instancePerName)))
                  + "\n\nYou can fix it adding a name when you call apply(): "
                  + "pipeline.apply(<name>, <transform>).");
        default:
          throw new IllegalArgumentException(
              "Unrecognized value for stable unique names: " + options.getStableUniqueNames());
      }
    }
  }

  /**
   * Returns a unique name for a transform with the given prefix (from enclosing transforms) and
   * initial name.
   */
  private String uniquifyInternal(String namePrefix, String origName) {
    String name = origName;
    int suffixNum = 2;
    while (true) {
      String candidate = buildName(namePrefix, name);
      if (usedFullNames.add(candidate)) {
        return candidate;
      }
      // A duplicate!  Retry.

View on GitHub (pinned to 12126d8942)

Solutions

1. Set --stableUniqueNames to one of the supported values: OFF, WARNING, or ERROR.
2. Check the PipelineOptions object: ensure getStableUniqueNames() returns a non-null CheckEnabled enum value.
3. Verify the Beam version's CheckEnabled enum and update any pinned configuration referencing removed values.

Example fix

// before
// --stableUniqueNames=ENFORCE  (unknown value)
// after
// --stableUniqueNames=ERROR  (or OFF/WARNING)

// Java: validate the option value before run
PipelineOptions opts = ...;
CheckEnabled v = opts.as(PipelineOptions.class).getStableUniqueNames();
if (v != CheckEnabled.OFF && v != CheckEnabled.WARNING && v != CheckEnabled.ERROR) {
  throw new IllegalArgumentException("stableUniqueNames must be OFF, WARNING, or ERROR");
}

try {
  pipeline.run();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unrecognized value for stable unique names")) {
    options.setStableUniqueNames(CheckEnabled.WARNING); // safe default, retry
    pipeline.run();
  } else { throw e; }
}

When it happens

Trigger: Passing an invalid value for the stableUniqueNames pipeline option, e.g. via --stableUniqueNames=<unknown> on the command line or a misconfigured options object, causing the enum lookup to yield a value the switch doesn't handle.

Common situations: Typo in the CLI flag value; a custom PipelineOptions implementation returning null; Beam version differences where the enum was renamed or had values removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown ValueKind number: {}
• Secret option string cannot be null
• Secret string must contain a valid type parameter
• Invalid secret type %s, currently supported types: %s
• Failed to parse secret option

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/9e9f7893891bee4b. Report an issue: GitHub.