What causes "Invalid RAR5 archive: ${reason}" in can1357/oh-my-pi?

Verify the archive integrity with `unrar t archive.rar` and re-download/re-copy if it fails

can1357/oh-my-pi · error · ArchiveError

Invalid RAR5 archive: ${reason}

Error message

Invalid RAR5 archive: ${reason}

What it means

Generic guard used throughout the RAR4/RAR5 decoders: any structural inconsistency while parsing headers or huffman-coded streams (bad sizes, invalid tables, out-of-range deltas, truncated data) raises 'Invalid RAR5 archive: <reason>'. It signals the byte stream does not conform to the RAR5 format at the point of failure.

Source

Thrown at packages/utils/src/ar/rar/rar5-decoder.ts:399

				writeI32(data, pos, address);
			}
		}
	}
}

function readI32(bytes: Uint8Array, offset: number): number {
	return bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24);
}

function writeI32(bytes: Uint8Array, offset: number, value: number): void {
	bytes[offset] = value;
	bytes[offset + 1] = value >>> 8;
	bytes[offset + 2] = value >>> 16;
	bytes[offset + 3] = value >>> 24;
}

function fail(reason: string): never {
	throw new ArchiveError(`Invalid RAR5 archive: ${reason}`);
}

View on GitHub (pinned to 9690622007)

Solutions

Verify the archive integrity with `unrar t archive.rar` and re-download/re-copy if it fails
Ensure the full file (all volumes for multi-part sets) is present and complete
Confirm you are passing a genuine RAR5 file (starts with 'Rar!\x1a\x07\x01\x00') and not a renamed/other archive

Defensive patterns

Strategy: validation

Validate before calling

const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
const rar5Sig = [0x52,0x61,0x72,0x21,0x1a,0x07,0x01,0x00];
if (!rar5Sig.every((b, i) => head[i] === b)) throw new Error('Not a RAR5 file');
if (file.size < 64) throw new Error('File too small to be a valid RAR');

Type guard

function hasRar5Signature(head: Uint8Array): boolean {
  return head.length >= 8 && head[0]===0x52 && head[1]===0x61 && head[2]===0x72 && head[3]===0x21
    && head[4]===0x1a && head[5]===0x07 && head[6]===0x01 && head[7]===0x00;
}

Try / catch

try {
  const reader = await readRar(source, { limits });
} catch (err) {
  if (err instanceof ArchiveError && err.message.startsWith('Invalid RAR5 archive')) {
    throw new Error(`Archive is corrupt or truncated: ${err.message}`);
  }
  throw err;
}

Prevention

Verify file size against the publisher's expected size before parsing
Run `unrar t` on untrusted archives before programmatic processing
Ensure complete multi-volume sets are present before reading
Detect signature mismatch early: check the first 8 bytes before handing the source to the library

When it happens

Trigger: parseRar5 or Rar5Decoder.decode() calling fail(reason) for malformed header sizes, invalid dictionary size (<128 KiB), filter ranges beyond unpacked size, bad huffman tables, or truncation mid-stream.

Common situations: Partially downloaded or truncated .rar files; passing a non-RAR file that coincidentally matched the 8-byte signature; bit-rotted archives on old storage; concatenated/multi-part archives opened without all volumes.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/b8746578e1685c0a. Report an issue: GitHub.