{"record":{"id":"ebbd7326d1628ce5","repo":"apache/beam","slug":"unknown-failure-mode-failuremode","errorCode":null,"errorMessage":"Unknown failure mode + failureMode","messagePattern":"Unknown failure mode \\+ failureMode","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerIO.java","lineNumber":2867,"sourceCode":"      // Batch upsert rows.\n      try {\n        mutationGroupBatchesReceived.inc();\n        mutationGroupsReceived.inc(mutations.size());\n        Iterable<Mutation> batch = Iterables.concat(mutations);\n        writeMutations(batch);\n        mutationGroupBatchesWriteSuccess.inc();\n        mutationGroupsWriteSuccess.inc(mutations.size());\n        return;\n      } catch (SpannerException e) {\n        mutationGroupBatchesWriteFail.inc();\n        if (failureMode == FailureMode.REPORT_FAILURES) {\n          // fall through and retry individual mutationGroups.\n        } else if (failureMode == FailureMode.FAIL_FAST) {\n          mutationGroupsWriteFail.inc(mutations.size());\n          LOG.error(\"Failed to write a batch of mutation groups\", e);\n          throw e;\n        } else {\n          throw new IllegalArgumentException(\"Unknown failure mode \" + failureMode);\n        }\n      }\n\n      // If we are here, writing a batch has failed, retry individual mutations.\n      for (MutationGroup mg : mutations) {\n        try {\n          spannerWriteRetries.inc();\n          writeMutations(mg);\n          mutationGroupsWriteSuccess.inc();\n        } catch (SpannerException e) {\n          mutationGroupsWriteFail.inc();\n          LOG.warn(\"Failed to write the mutation group: {}\", mg, e);\n          c.output(failedTag, mg);\n        }\n      }\n    }\n\n    /*","sourceCodeStart":2849,"sourceCodeEnd":2885,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerIO.java#L2849-L2885","documentation":"SpannerIO's write batch retry loop only understands FailureMode.ALLOW_FAIL_FAST/FAIL_FAST semantics; if the configured FailureMode is not one it recognizes, it throws IllegalArgumentException(\"Unknown failure mode \" + failureMode). This is an internal defensive check: the enum should never hold an unknown value, so hitting it indicates a non-standard FailureMode instance reached the write path.","triggerScenarios":"Calling SpannerIO.write()/Write mutation group batching where failureMode (set via withFailureMode) is neither a recognized enum constant handled by the if/else chain — practically only possible with a custom/modified FailureMode enum or incompatibility between a compiled spanner package version and Beam's SpannerIO.","commonSituations":"Mixing Beam versions (e.g., a shaded/relocated Google Cloud spanner connector providing its own FailureMode), bytecode manipulation, or a version mismatch where a newer FailureMode constant is passed into an older SpannerIO that doesn't handle it.","solutions":["Check that withFailureMode() is only called with a value from the org.apache.beam.sdk.io.gcp.spanner.SpannerIO.FailureMode enum of the Beam version on the classpath.","Align all Beam SDK module versions (mvn dependency:tree; exclude conflicting beam-sdks-java-io-google-cloud-platform versions).","Upgrade Beam to the latest patch release if a shading/relocation conflict is suspected.","If the error persists without custom code, report it as a bug with the failureMode value from the message."],"exampleFix":"// before (conceptual: passing a value from a mismatched/relocated enum)\nio.gcp.spanner.FailureMode mode = otherLib.getFailureMode();\nSpannerIO.write().withFailureMode(mode);\n// after\nSpannerIO.write().withFailureMode(SpannerIO.FailureMode.FAIL_FAST);","handlingStrategy":"validation","validationCode":"if (!EnumSet.allOf(SpannerIO.FailureMode.class).contains(mode)) {\n  throw new IllegalArgumentException(\"Unsupported FailureMode: \" + mode);\n}","typeGuard":null,"tryCatchPattern":"try { write = SpannerIO.write().withFailureMode(SpannerIO.FailureMode.FAIL_FAST); } catch (IllegalArgumentException e) { LOG.error(\"Bad failureMode config\", e); }","preventionTips":["Only pass enum constants from the same Beam version's SpannerIO.FailureMode.","Avoid mixing relocated/shaded spanner connector jars on the classpath."],"tags":["java","beam","spanner","illegal-argument","enum"],"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-14T21:17:11.552Z"}