apache/beam · error · IllegalArgumentException

Unknown failure mode + failureMode

Error message

Unknown failure mode + failureMode

What it means

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.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerIO.java:2867

      // Batch upsert rows.
      try {
        mutationGroupBatchesReceived.inc();
        mutationGroupsReceived.inc(mutations.size());
        Iterable<Mutation> batch = Iterables.concat(mutations);
        writeMutations(batch);
        mutationGroupBatchesWriteSuccess.inc();
        mutationGroupsWriteSuccess.inc(mutations.size());
        return;
      } catch (SpannerException e) {
        mutationGroupBatchesWriteFail.inc();
        if (failureMode == FailureMode.REPORT_FAILURES) {
          // fall through and retry individual mutationGroups.
        } else if (failureMode == FailureMode.FAIL_FAST) {
          mutationGroupsWriteFail.inc(mutations.size());
          LOG.error("Failed to write a batch of mutation groups", e);
          throw e;
        } else {
          throw new IllegalArgumentException("Unknown failure mode " + failureMode);
        }
      }

      // If we are here, writing a batch has failed, retry individual mutations.
      for (MutationGroup mg : mutations) {
        try {
          spannerWriteRetries.inc();
          writeMutations(mg);
          mutationGroupsWriteSuccess.inc();
        } catch (SpannerException e) {
          mutationGroupsWriteFail.inc();
          LOG.warn("Failed to write the mutation group: {}", mg, e);
          c.output(failedTag, mg);
        }
      }
    }

    /*

View on GitHub (pinned to 12126d8942)

Solutions

1. 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.
2. Align all Beam SDK module versions (mvn dependency:tree; exclude conflicting beam-sdks-java-io-google-cloud-platform versions).
3. Upgrade Beam to the latest patch release if a shading/relocation conflict is suspected.
4. If the error persists without custom code, report it as a bug with the failureMode value from the message.

Example fix

// before (conceptual: passing a value from a mismatched/relocated enum)
io.gcp.spanner.FailureMode mode = otherLib.getFailureMode();
SpannerIO.write().withFailureMode(mode);
// after
SpannerIO.write().withFailureMode(SpannerIO.FailureMode.FAIL_FAST);

if (!EnumSet.allOf(SpannerIO.FailureMode.class).contains(mode)) {
  throw new IllegalArgumentException("Unsupported FailureMode: " + mode);
}

try { write = SpannerIO.write().withFailureMode(SpannerIO.FailureMode.FAIL_FAST); } catch (IllegalArgumentException e) { LOG.error("Bad failureMode config", e); }

When it happens

Trigger: 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.

Common situations: 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.

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

• Unrecognized dialect: + dialect.name()
• Unrecognized value for stable unique names:
• Unknown ValueKind number: {}
• Cannot merge schemas with different numbers of fields. schem
• Unsupported type of %s: %s

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