paperclipai/paperclip · error

HEIF box exceeds file bounds

Error message

HEIF box exceeds file bounds

What it means

The ISO-BMFF walker validates every box's size: with a standard header a box must be at least 8 bytes, and the box must not extend past the end of its container range (at + size > end). Violating either throws "HEIF box exceeds file bounds". For extended-size boxes this also fires when the 64-bit largesize exceeds the whole buffer (media.ts:32-33, 37-38).

Solutions

1. Treat the file as corrupt/malicious and reject it; obtain a fresh copy and re-upload.
2. Verify integrity: compare checksums if the source provides them; run `ffprobe` locally.
3. Re-export the image from the original app (e.g. Photos export) instead of repairing bytes.
4. Keep the guard in place — it protects native decoders from out-of-bounds reads.

Example fix

// before: heic whose mdat declares size beyond EOF
// after: re-export the image
heif-convert good.heic out.jpg  # verify a known-good copy first

function boxWithinBounds(buf: Buffer, at: number, size: number, header: number, end: number): boolean {
  return size >= header && at + size <= end;
}

function isBoundedBox(b: Buffer, extendedSize: bigint): boolean {
  return extendedSize <= BigInt(b.length);
}

try {
  validateHeifDimensions(body);
} catch (e) {
  if (e instanceof Error && e.message === "HEIF box exceeds file bounds") {
    return rejectUpload("HEIF declares boxes beyond the file; file is corrupt or hostile");
  }
  throw e;
}

When it happens

Trigger: Any box whose declared size is smaller than its header or whose at+size exceeds the enclosing container end; or an extended (largesize) box whose 64-bit size is greater than the total buffer length.

Common situations: Corrupted or maliciously crafted HEIC claiming absurd sizes (classic parser-overflow pattern); truncated download where a parent container's declared size exceeds the bytes received; bit rot in stored files.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• HEIF file type is missing
• HEIF metadata nesting is too deep
• Invalid HEIF image dimensions
• Invalid HEIF box length
• Invalid HEIF box structure

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/f822e2a15e1fcf7d. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/photon/media.ts:33

/** Validate bounded ISO-BMFF structure before invoking any native decoder. */
export function validateHeifDimensions(body: Buffer): void {
  let boxes = 0;
  let dimensions = 0;
  let totalPixels = 0;
  let branded = false;
  const visit = (start: number, end: number, depth: number) => {
    if (depth > 8) throw new Error("HEIF metadata nesting is too deep");
    for (let at = start; at < end; ) {
      if (++boxes > 4096 || end - at < 8)
        throw new Error("Invalid HEIF box structure");
      let size = body.readUInt32BE(at);
      const type = body.toString("ascii", at + 4, at + 8);
      let header = 8;
      if (size === 1) {
        if (end - at < 16) throw new Error("Invalid HEIF box length");
        const extended = body.readBigUInt64BE(at + 8);
        if (extended > BigInt(body.length))
          throw new Error("HEIF box exceeds file bounds");
        size = Number(extended);
        header = 16;
      } else if (size === 0) size = end - at;
      if (size < header || at + size > end)
        throw new Error("HEIF box exceeds file bounds");
      const content = at + header;
      if (type === "ftyp") {
        if (size < header + 8) throw new Error("HEIF file type is missing");
        const brands = body.toString("ascii", content, at + size);
        branded = /heic|heix|hevc|hevx|mif1|msf1/.test(brands);
      } else if (type === "ispe") {
        if (size !== header + 12)
          throw new Error("Invalid HEIF image dimensions");
        const width = body.readUInt32BE(content + 4);
        const height = body.readUInt32BE(content + 8);
        if (
          !width ||
          !height ||

View on GitHub (pinned to 3f1d897a7c)