What causes "Unrecognized uint64 behavior: ${behavior.name()}" in apache/beam?

Set uint64Behavior to one of SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, CONVERT_TO_BIG_DECIMAL.

apache/beam · error · IllegalStateException

Unrecognized uint64 behavior

Error message

Unrecognized uint64 behavior: ${behavior.name()}

What it means

This IllegalStateException is thrown by PrimitiveSbeField.convertUint64 when the configured uint64Behavior matches none of the handled Behavior cases and falls to the default branch. It is an exhaustiveness guard against unknown or version-mismatched behavior values for 64-bit unsigned fields.

Solutions

Set uint64Behavior to one of SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, CONVERT_TO_BIG_DECIMAL.
Keep SbeFieldOptions and PrimitiveSbeField from the same Beam version.
Fix the uint64 behavior setting in SBE pipeline options.
Validate behavior values before running the transform.

Example fix

// before
options.setUint64Behavior(unknownBehavior);
// after
options.setUint64Behavior(Behavior.SAME_BIT_SIGNED);

Defensive patterns

Strategy: validation

Validate before calling

Behavior b = options.unsignedOptions().uint64Behavior();
if (b != Behavior.SAME_BIT_SIGNED && b != Behavior.HIGHER_BIT_SIGNED
    && b != Behavior.CONVERT_TO_STRING && b != Behavior.CONVERT_TO_BIG_DECIMAL) {
  throw new IllegalArgumentException("unsupported uint64Behavior: " + b);
}

Try / catch

try {
  pipeline.apply(SbeIO.readMessages(...));
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unrecognized uint64 behavior")) {
    // set a supported uint64Behavior and rebuild the pipeline
  }
}

Prevention

Use only supported Behavior values for uint64Behavior.
Keep enum producers and consumers on the same Beam version.
Validate unsigned behaviors immediately after options construction.
Avoid ad-hoc enum values from configuration strings.

When it happens

Trigger: Translating a uint64 SBE field whose SbeFieldOptions.unsignedOptions().uint64Behavior() holds a Behavior value not handled by the switch.

Common situations: New Behavior enum constants introduced in one component but not the other; options objects built incorrectly at runtime.

Related errors

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

Appendix: source

Thrown at sdks/java/extensions/sbe/src/main/java/org/apache/beam/sdk/extensions/sbe/PrimitiveSbeField.java:138

      default:
        throw new IllegalStateException("Unrecognized uint32 behavior: " + behavior.name());
    }
  }

  private static FieldType convertUint64(SbeFieldOptions options) {
    Behavior behavior = options.unsignedOptions().uint64Behavior();
    switch (behavior) {
      case SAME_BIT_SIGNED:
        return FieldType.INT64;
      case HIGHER_BIT_SIGNED:
        throw new IllegalStateException(
            "Options say to use higher bit type, but that is impossible for 64-bit integers.");
      case CONVERT_TO_STRING:
        return FieldType.STRING;
      case CONVERT_TO_BIG_DECIMAL:
        return FieldType.DECIMAL;
      default:
        throw new IllegalStateException("Unrecognized uint64 behavior: " + behavior.name());
    }
  }

  public static Builder builder() {
    return new AutoValue_PrimitiveSbeField.Builder();
  }

  /** Builder for {@link PrimitiveSbeField}. */
  @AutoValue.Builder
  public abstract static class Builder {

    public abstract Builder setName(String value);

    public abstract Builder setIsRequired(Boolean value);

    public abstract Builder setType(PrimitiveType value);

    public abstract PrimitiveSbeField build();

View on GitHub (pinned to 12126d8942)