clockworklabs/SpacetimeDB · error · Error

Uint8Array is not 32 bytes long: [${array}]

Error message

Uint8Array is not 32 bytes long: [${array}]

What it means

uint8ArrayToU256 interprets the bytes as a little-endian 256-bit integer via BinaryReader.readU256, so exactly 32 bytes are required; any other length throws. It backs hexStringToU256, so hex input decoding to the wrong byte count also lands here.

Source

Thrown at crates/bindings-typescript/src/lib/util.ts:55

  return true;
}

export function uint8ArrayToHexString(array: Uint8Array): string {
  return Array.prototype.map
    .call(array.reverse(), x => ('00' + x.toString(16)).slice(-2))
    .join('');
}

export function uint8ArrayToU128(array: Uint8Array): bigint {
  if (array.length != 16) {
    throw new Error(`Uint8Array is not 16 bytes long: ${array}`);
  }
  return new BinaryReader(array).readU128();
}

export function uint8ArrayToU256(array: Uint8Array): bigint {
  if (array.length != 32) {
    throw new Error(`Uint8Array is not 32 bytes long: [${array}]`);
  }
  return new BinaryReader(array).readU256();
}

export function hexStringToUint8Array(str: string): Uint8Array {
  if (str.startsWith('0x')) {
    str = str.slice(2);
  }
  const matches = str.match(/.{1,2}/g) || [];
  const data = Uint8Array.from(
    matches.map((byte: string) => parseInt(byte, 16))
  );
  return data.reverse();
}

export function hexStringToU128(str: string): bigint {
  return uint8ArrayToU128(hexStringToUint8Array(str));
}

View on GitHub (pinned to 524b4487d9)

Solutions

1. Validate array.length === 32 before calling
2. Check the source hex string: after stripping '0x' it must be exactly 64 hex chars
3. Use uint8ArrayToU128 for 16-byte values

Example fix

// before
const v = uint8ArrayToU256(hexStringToUint8Array('0x' + 'ab'.repeat(16))); // 16 bytes -> throws

// after
const v = uint8ArrayToU256(hexStringToUint8Array('0x' + 'ab'.repeat(32))); // exactly 32 bytes

function isU256Bytes(array: Uint8Array): boolean {
  return array.length === 32;
}
// if (!isU256Bytes(bytes)) throw new TypeError(`expected 32 bytes, got ${bytes.length}`);

When it happens

Trigger: Passing a Uint8Array whose length is not 32 directly, or a hex string that decodes to a non-32-byte array - e.g. a 16-byte u128 hex (32 chars) fed to the u256 helper.

Common situations: Confusing 128-bit and 256-bit id widths; slicing with wrong offsets or lengths; hex strings with odd length or missing padding.

Related errors

• Uint8Array is not 16 bytes long: ${array}
• UUID v4 requires 16 bytes
• Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`
• Index '${indexLabel}' on table '${tableLabel}' must define a
• Timestamp is outside of the representable range of JS's Date

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/6c94273e412a1418. Report an issue: GitHub.