apache/beam · error · IllegalStateException

Options say to use higher bit type, but that is impossible…

Error message

Options say to use higher bit type, but that is impossible for 64-bit integers.

What it means

This IllegalStateException is thrown by PrimitiveSbeField.convertUint64 when uint64Behavior is HIGHER_BIT_SIGNED. Widening a 64-bit unsigned integer to a higher-bit signed type is impossible (there is no 128-bit signed FieldType), so the extension rejects this configuration explicitly instead of overflowing values.

Solutions

Change uint64Behavior to SAME_BIT_SIGNED (map to int64), CONVERT_TO_STRING, or CONVERT_TO_BIG_DECIMAL.
Use CONVERT_TO_BIG_DECIMAL or CONVERT_TO_STRING when full uint64 range must be preserved.
Add a special case for uint64 when generating options programmatically.
Document/validate that HIGHER_BIT_SIGNED is only valid for uint8/16/32.

Example fix

// before
options.setUint64Behavior(Behavior.HIGHER_BIT_SIGNED);
// after
options.setUint64Behavior(Behavior.CONVERT_TO_BIG_DECIMAL);

Defensive patterns

Strategy: validation

Validate before calling

if (options.unsignedOptions().uint64Behavior() == Behavior.HIGHER_BIT_SIGNED) {
  throw new IllegalArgumentException("HIGHER_BIT_SIGNED invalid for uint64; use SAME_BIT_SIGNED, CONVERT_TO_STRING, or CONVERT_TO_BIG_DECIMAL");
}

Try / catch

try {
  pipeline.apply(SbeIO.readMessages(...));
} catch (IllegalStateException e) {
  if (e.getMessage().contains("impossible for 64-bit integers")) {
    // switch uint64Behavior to SAME_BIT_SIGNED or CONVERT_TO_STRING/BIG_DECIMAL
  }
}

Prevention

Never apply HIGHER_BIT_SIGNED to uint64 fields.
Use CONVERT_TO_BIG_DECIMAL or CONVERT_TO_STRING to preserve full uint64 range.
Special-case 64-bit fields when generating options programmatically.
Validate behavior-per-primitive-type mapping before submission.

When it happens

Trigger: Configuring SbeFieldOptions.unsignedOptions().uint64Behavior() = Behavior.HIGHER_BIT_SIGNED and translating a uint64 SBE field via beamType().

Common situations: Applying a uniform 'use higher bit signed' policy to all unsigned fields without special-casing 64-bit; copying uint8/16/32 option setup to uint64.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

        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());
    }
  }

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

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

View on GitHub (pinned to 12126d8942)