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

Set uint32Behavior to SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, or CONVERT_TO_BIG_DECIMAL.

apache/beam · error · IllegalStateException

Unrecognized uint32 behavior

Error message

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

What it means

This IllegalStateException is thrown by PrimitiveSbeField.convertUint32 when the configured uint32Behavior is not among the Behavior values handled in the switch. Like its uint8/uint16 counterparts, it is a default-branch guard that fails fast rather than mapping a 32-bit unsigned field to an unintended Beam FieldType.

Solutions

Set uint32Behavior to SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, or CONVERT_TO_BIG_DECIMAL.
Use matching Beam/SBE extension versions so enum and switch are consistent.
Correct the uint32 behavior in SBE pipeline options.
Validate configured behaviors before schema translation.

Example fix

// before
options.setUint32Behavior(someInvalidBehavior);
// after
options.setUint32Behavior(Behavior.CONVERT_TO_BIG_DECIMAL);

Defensive patterns

Strategy: validation

Validate before calling

Behavior b = options.unsignedOptions().uint32Behavior();
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 uint32Behavior: " + b);
}

Try / catch

try {
  pipeline.apply(SbeIO.readMessages(...));
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unrecognized uint32 behavior")) {
    // fix uint32Behavior in options and rebuild
  }
}

Prevention

Use documented Behavior values for uint32Behavior.
Keep SbeFieldOptions construction in one versioned module.
Validate all unsigned behaviors before translation.
Prefer explicit named constants over dynamic behavior lookup.

When it happens

Trigger: Translating a uint32 SBE field whose SbeFieldOptions.unsignedOptions().uint32Behavior() contains a Behavior value the switch does not recognize.

Common situations: Behavior enum/switch drift across Beam versions; options built programmatically with values outside the supported set.

Related errors

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

Appendix: source

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

        return FieldType.DECIMAL;
      default:
        throw new IllegalStateException("Unrecognized uint16 behavior: " + behavior.name());
    }
  }

  private static FieldType convertUint32(SbeFieldOptions options) {
    Behavior behavior = options.unsignedOptions().uint32Behavior();
    switch (behavior) {
      case SAME_BIT_SIGNED:
        return FieldType.INT32;
      case HIGHER_BIT_SIGNED:
        return FieldType.INT64;
      case CONVERT_TO_STRING:
        return FieldType.STRING;
      case CONVERT_TO_BIG_DECIMAL:
        return FieldType.DECIMAL;
      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());
    }

View on GitHub (pinned to 12126d8942)