What causes "value length {} > allowed length {}" in apache/beam?

Increase the FixedBytes length argument to at least the maximum value size.

apache/beam · error · ValueError

value length > allowed length

Error message

value length {} > allowed length {}

What it means

The fixed-bytes logical type (FixedBytes, from a length argument) rejects values longer than the declared length in to_language_type(). Shorter values are zero-padded to the fixed length; longer values raise ValueError because fixed-width bytes cannot hold them.

Solutions

Increase the FixedBytes length argument to at least the maximum value size.
Truncate or hash values to fit the declared length before conversion.
Switch to a variable-length Bytes logical type (or plain bytes) if sizes are not truly fixed.

Example fix

// before
FixedBytes(length=4).to_language_type(b'hello')  # ValueError

// after
FixedBytes(length=8).to_language_type(b'hello')  # b'hello\x00\x00\x00'

Defensive patterns

Strategy: validation

Validate before calling

def fits_fixed_bytes(value: bytes, length: int) -> bool:
    return len(value) <= length

Try / catch

try:
    out = fixed_bytes_lt.to_language_type(value)
except ValueError:
    out = fixed_bytes_lt.to_language_type(value[:fixed_bytes_lt.length])  # truncate

Prevention

Set FixedBytes length to the exact known payload size (e.g. digest size of your hash).
Assert value lengths at data-production time, before schema conversion.
Prefer variable-length bytes when sizes can vary.

When it happens

Trigger: Converting a bytes value whose len(value) exceeds the FixedBytes logical type's length, e.g. FixedBytes(length=4).to_language_type(b'toolong'); decoding schema data whose underlying bytes grew beyond the declared fixed width.

Common situations: Declaring a fixed byte width smaller than actual payload (e.g. hashing with SHA-256 but declaring length=16); schema evolved to wider values after the fixed length was fixed at write time; miscounting expected field width.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/schemas.py:1317

@LogicalType._register_internal
class FixedBytes(PassThroughLogicalType[bytes, np.int32]):
  """A logical type for fixed-length bytes."""
  @classmethod
  def urn(cls):
    return common_urns.fixed_bytes.urn

  def __init__(self, length: np.int32):
    self.length = length

  @classmethod
  def language_type(cls) -> type:
    return bytes

  def to_language_type(self, value: bytes):
    length = len(value)
    if length > self.length:
      raise ValueError(
          "value length {} > allowed length {}".format(length, self.length))
    elif length < self.length:
      # padding at the end
      value = value + b'\0' * (self.length - length)

    return value

  @classmethod
  def argument_type(cls):
    return np.int32

  def argument(self):
    return self.length


@LogicalType._register_internal
class VariableBytes(PassThroughLogicalType[bytes, np.int32]):
  """A logical type for variable-length bytes with specified maximum length."""

View on GitHub (pinned to 12126d8942)