paperclipai/paperclip · error

Invalid HEIF image dimensions

Error message

Invalid HEIF image dimensions

What it means

An ispe (image spatial extent) box must be exactly header + 12 bytes (version/flags 4 + width 4 + height 4). Any other size throws "Invalid HEIF image dimensions". This precedes reading width/height so the parser never reads dimensions from a malformed box.

Solutions

1. Reject the file and re-export a clean HEIC/HEIC from the origin application.
2. Validate locally with `heif-info`/`ffprobe` — a nonconformant ispe means a broken encoder was used.
3. Re-encode with a mainstream tool (sips, ImageMagick with HEIF support, libheif's heif-enc).
4. If the file is hostile input, keep it blocked; the exact-size check is intentional.

Example fix

// before: malformed ispe (size 24)
// after: re-encode with libheif
heif-enc input.jpg -o output.heic

function ispeSizeValid(buf: Buffer, at: number): boolean {
  const size = buf.readUInt32BE(at);
  const header = size === 1 ? 16 : 8;
  return size === header + 12;
}

function isWellFormedIspe(b: Buffer, boxStart: number): boolean {
  return b.readUInt32BE(boxStart) === 20;
}

try {
  validateHeifDimensions(body);
} catch (e) {
  if (e instanceof Error && e.message === "Invalid HEIF image dimensions") {
    return rejectUpload("HEIF spatial-extent box is malformed; re-encode the image");
  }
  throw e;
}

When it happens

Trigger: An ispe box whose total size is not exactly 20 bytes (8-byte header + 12 content) encountered while walking the iprp/ipco property containers (media.ts:44-46).

Common situations: Corrupted or deliberately malformed HEIC with oversized/undersized ispe; files produced by nonconformant encoders; fuzzed inputs probing dimension parsing.

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 box exceeds file bounds
• HEIF metadata nesting is too deep
• Invalid HEIF box length
• Invalid HEIF box structure

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

Appendix: source

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

      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 ||
          width > 16_384 ||
          height > 16_384 ||
          width * height > MAX_PIXELS
        )
          throw new Error("HEIF decoded image exceeds the pixel limit");
        totalPixels += width * height;
        if (totalPixels > MAX_PIXELS * 3 || ++dimensions > 512)
          throw new Error("HEIF image collection exceeds the pixel limit");
      } else if (["meta", "iprp", "ipco"].includes(type)) {
        visit(content + (type === "meta" ? 4 : 0), at + size, depth + 1);
      }
      at += size;
    }

View on GitHub (pinned to 3f1d897a7c)