earendil-works/pi · error · TypeError

Frame payload must be a Uint8Array

Error message

Frame payload must be a Uint8Array

What it means

Error "Frame payload must be a Uint8Array" thrown in earendil-works/pi.

Source

Thrown at packages/protocol/src/framing.ts:29

export class FrameError extends Error {
	constructor(message: string) {
		super(message);
		this.name = "FrameError";
	}
}

function resolveMaxFrameLength(options: FrameDecoderOptions | undefined): number {
	const value = options?.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
	if (!Number.isSafeInteger(value) || value < 0 || value > MAX_UINT32) {
		throw new RangeError(`maxFrameLength must be an integer between 0 and ${MAX_UINT32}`);
	}
	return value;
}

/** Prefixes a payload with its unsigned 32-bit big-endian byte length. */
export function encodeFrame(payload: Uint8Array): Uint8Array {
	if (!(payload instanceof Uint8Array)) throw new TypeError("Frame payload must be a Uint8Array");
	if (payload.byteLength > MAX_UINT32) throw new RangeError("Frame payload exceeds the unsigned 32-bit length limit");
	const frame = new Uint8Array(FRAME_HEADER_LENGTH + payload.byteLength);
	const length = payload.byteLength;
	frame[0] = length >>> 24;
	frame[1] = length >>> 16;
	frame[2] = length >>> 8;
	frame[3] = length;
	frame.set(payload, FRAME_HEADER_LENGTH);
	return frame;
}

/** Validates that bytes contain exactly one complete frame within the configured limit. */
export function assertCompleteFrame(frame: Uint8Array, options?: FrameDecoderOptions): void {
	if (!(frame instanceof Uint8Array)) throw new TypeError("Frame must be a Uint8Array");
	if (frame.byteLength < FRAME_HEADER_LENGTH) throw new FrameError("Frame does not contain a complete length prefix");
	const length = frame[0]! * 0x1_000_000 + frame[1]! * 0x1_0000 + frame[2]! * 0x100 + frame[3]!;
	const maxFrameLength = resolveMaxFrameLength(options);
	if (length > maxFrameLength) {

View on GitHub (pinned to 4af9d21d3b)

Solutions

1. Pass the frame payload as a Uint8Array.

When it happens

Trigger: Thrown at packages/protocol/src/framing.ts:29 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of earendil-works/pi@4af9d21d3b (2026-08-24). Data as JSON: /api/errors/1718ccac80c98096. Report an issue: GitHub.