What causes "Invalid HEIF box length" in paperclipai/paperclip?

Obtain an intact copy of the image and re-upload; the file is structurally truncated.

Invalid HEIF box length

Error message

Invalid HEIF box length

What it means

When an ISO-BMFF box uses the 64-bit extended size encoding (32-bit size field === 1), the walker requires at least 16 bytes (8-byte header + 8-byte largesize) to be present. If fewer remain it throws "Invalid HEIF box length" — the box header claims an extended size that cannot fit in the buffer.

Solutions

Obtain an intact copy of the image and re-upload; the file is structurally truncated.
Check the transfer path (proxy, resumable upload) that cut the file short and fix it.
Validate locally with `ffprobe`/`mp4dump` before submitting to confirm box integrity.
Do not bypass: a size===1 box near EOF is invalid per ISO 14496-12.

Example fix

// before: uploading partial file.heic (10 bytes left, size==1 box)
// after: re-download and verify
ffprobe file.heic  # must parse cleanly before upload

Defensive patterns

Strategy: validation

Validate before calling

// ensure no size==1 box sits within the last 16 bytes
function noTruncatedExtendedBox(buf: Buffer): boolean {
  for (let at = 0; at + 8 <= buf.length; ) {
    const size = buf.readUInt32BE(at);
    if (size === 1 && buf.length - at < 16) return false;
    if (size === 0) break;
    if (size < 8) return false;
    at += size;
  }
  return true;
}

Type guard

function hasCompleteHeader(b: Buffer, at: number): boolean {
  const size = b.readUInt32BE(at);
  return size !== 1 || b.length - at >= 16;
}

Try / catch

try {
  validateHeifDimensions(body);
} catch (e) {
  if (e instanceof Error && e.message === "Invalid HEIF box length") {
    return rejectUpload("File appears truncated; re-download and retry");
  }
  throw e;
}

Prevention

Use resumable/integrity-checked transfers so partial files never reach validation.
Compare uploaded byte length against expected size when the source provides it.
Run ffprobe on files client-side before upload where possible.
Never hand-edit binary media; re-export instead.

When it happens

Trigger: A box with size field 1 located fewer than 16 bytes from the end of the current container range (media.ts:29-30), typically a truncated or hand-crafted buffer.

Common situations: Truncated HEIC download where the last box header was cut; maliciously crafted file with a size===1 box at the tail; byte-level corruption flipping a normal size field to 1.

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

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

Appendix: source

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

  "image/heif-sequence",
]);

/** 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);

View on GitHub (pinned to 3f1d897a7c)