apache/beam · error · IllegalStateException

Unrecognized uint8 behavior

Error message

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

What it means

This IllegalStateException is thrown by PrimitiveSbeField.convertUint8 when the configured uint8Behavior does not match any known Behavior enum value in the switch. It is an internal exhaustiveness guard: the Behavior configured via SbeFieldOptions was not one of SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, or CONVERT_TO_BIG_DECIMAL as handled here.

Solutions

  1. Set uint8Behavior to one of the supported values: SAME_BIT_SIGNED, HIGHER_BIT_SIGNED, CONVERT_TO_STRING, CONVERT_TO_BIG_DECIMAL.
  2. Align the Beam/SBE extension versions so SbeFieldOptions and PrimitiveSbeField agree on the Behavior enum.
  3. Inspect the SBE pipeline options for the uint8 behavior setting and correct it.
  4. Validate the configured behavior before building the transform.

Example fix

// before
options.setUint8Behavior(unrecognizedBehavior);
// after
options.setUint8Behavior(Behavior.CONVERT_TO_STRING);
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  pipeline.apply(SbeIO.readMessages(...));
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Unrecognized uint8 behavior")) {
    // correct options and retry pipeline construction
  }
}

Prevention

When it happens

Trigger: Configuring SbeFieldOptions.unsignedOptions().uint8Behavior() with a Behavior value the switch does not handle, then translating a uint8 SBE field's Beam type.

Common situations: Version mismatch between the code building SbeFieldOptions (knows a new Behavior value) and this switch (written before it); programmatic construction of options with null or exotic values.

Related errors

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

Appendix: source

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

      default:
        throw new IllegalStateException(
            "Got a state that is not recognized: " + type().primitiveName());
    }
  }

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

View on GitHub (pinned to 12126d8942)