{"record":{"id":"9e9f7893891bee4b","repo":"apache/beam","slug":"unrecognized-value-for-stable-unique-names","errorCode":null,"errorMessage":"Unrecognized value for stable unique names: ","messagePattern":"Unrecognized value for stable unique names: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/Pipeline.java","lineNumber":635,"sourceCode":"        case WARNING:\n          LOG.warn(\n              \"The following transforms do not have stable unique names: {}\",\n              Joiner.on(\", \").join(transform(errors, new KeysExtractor())));\n          break;\n        case ERROR: // be very verbose here since it will just fail the execution\n          throw new IllegalStateException(\n              String.format(\n                      \"Pipeline update will not be possible because the following transforms do\"\n                          + \" not have stable unique names: %s.\",\n                      Joiner.on(\", \").join(transform(errors, new KeysExtractor())))\n                  + \"\\n\\n\"\n                  + \"Conflicting instances:\\n\"\n                  + Joiner.on(\"\\n\")\n                      .join(transform(errors, new UnstableNameToMessage(instancePerName)))\n                  + \"\\n\\nYou can fix it adding a name when you call apply(): \"\n                  + \"pipeline.apply(<name>, <transform>).\");\n        default:\n          throw new IllegalArgumentException(\n              \"Unrecognized value for stable unique names: \" + options.getStableUniqueNames());\n      }\n    }\n  }\n\n  /**\n   * Returns a unique name for a transform with the given prefix (from enclosing transforms) and\n   * initial name.\n   */\n  private String uniquifyInternal(String namePrefix, String origName) {\n    String name = origName;\n    int suffixNum = 2;\n    while (true) {\n      String candidate = buildName(namePrefix, name);\n      if (usedFullNames.add(candidate)) {\n        return candidate;\n      }\n      // A duplicate!  Retry.","sourceCodeStart":617,"sourceCodeEnd":653,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/Pipeline.java#L617-L653","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typo in the CLI flag value; a custom PipelineOptions implementation returning null; Beam version differences where the enum was renamed or had values removed.","solutions":["Set --stableUniqueNames to one of the supported values: OFF, WARNING, or ERROR.","Check the PipelineOptions object: ensure getStableUniqueNames() returns a non-null CheckEnabled enum value.","Verify the Beam version's CheckEnabled enum and update any pinned configuration referencing removed values."],"exampleFix":"// before\n// --stableUniqueNames=ENFORCE  (unknown value)\n// after\n// --stableUniqueNames=ERROR  (or OFF/WARNING)","handlingStrategy":"validation","validationCode":"// Java: validate the option value before run\nPipelineOptions opts = ...;\nCheckEnabled v = opts.as(PipelineOptions.class).getStableUniqueNames();\nif (v != CheckEnabled.OFF && v != CheckEnabled.WARNING && v != CheckEnabled.ERROR) {\n  throw new IllegalArgumentException(\"stableUniqueNames must be OFF, WARNING, or ERROR\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  pipeline.run();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Unrecognized value for stable unique names\")) {\n    options.setStableUniqueNames(CheckEnabled.WARNING); // safe default, retry\n    pipeline.run();\n  } else { throw e; }\n}","preventionTips":["Use only documented values (OFF/WARNING/ERROR) for --stableUniqueNames","Avoid custom option types shadowing CheckEnabled","Sanitize CLI-generated options before constructing the Pipeline"],"tags":["java","beam","configuration","enum","cli"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}