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

Set uint16Behavior to a supported Behavior value.

apache/beam · error · IllegalStateException

Unrecognized uint16 behavior

Error message

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

What it means

This IllegalStateException is thrown by PrimitiveSbeField.convertUint16 when the configured uint16Behavior is not one of the Behavior values handled in the switch. It is an exhaustiveness/default-branch guard preventing an unknown unsigned-16-bit behavior from silently producing a wrong Beam FieldType.

Solutions

Set uint16Behavior to a supported Behavior value.
Upgrade or downgrade so the SbeFieldOptions Behavior enum and the switch logic come from the same Beam version.
Check and fix the SBE pipeline options defining uint16 behavior.
Add pre-translation validation of behavior values.

Example fix

// before
options.setUint16Behavior(Behavior.HIGHER_BIT_SIGNED_UNHANDLED);
// after
options.setUint16Behavior(Behavior.HIGHER_BIT_SIGNED);

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Use only supported Behavior values for uint16Behavior.
Version-align SbeFieldOptions usage with the Beam SBE extension.
Validate options before pipeline submission.
Avoid cross-version serialization of behavior settings.

When it happens

Trigger: Translating a uint16 SBE field whose SbeFieldOptions.unsignedOptions().uint16Behavior() holds a Behavior value absent from the switch (not SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, CONVERT_TO_BIG_DECIMAL).

Common situations: Mismatched versions where a new Behavior constant was added to the enum but not this switch; corrupted or hand-built options objects.

Related errors

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

Appendix: source

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

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

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

View on GitHub (pinned to 12126d8942)