ErrLookup › Background articles › "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them

"File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them

"File too large", "file size exceeds limit", "Image must be less than XMB", and "exceeds the input size limit" are size-cap errors raised before or during a file operation when an input exceeds a library's configured maximum. Developers hit them when uploading media or archives, importing large recordings, passing big payloads to APIs, or processing files whose size a helper refuses to read into memory.

Distilled from 95 documented records across 46 repositories.

Background

This family sits at a deliberate boundary: nearly every implementation checks the file's byte size against a hard cap before committing an expensive or dangerous operation — reading bytes into memory, base64-encoding for an AI provider, uploading to storage, or POSTing to a transcription API. The caps exist for concrete reasons. Meetily's 20 GiB audio cap and GitNexus's 512 KiB index cap exist because files are decoded or read whole into memory (meetily accumulates all samples into a Vec<f32>, multiplying the compressed size several-fold). Zeroclaw's 25 MB audio ceiling and Gumroad's image cap mirror upstream provider limits (Whisper-compatible cloud APIs and Stripe's combined evidence budget, respectively). Others bound artifacts by design: CodeWhale refuses lane exit receipts over 4 KiB so the receipt stays a fixed-size, cheap-to-validate file, and zeroclaw's 50 MB WASM cap rejects modules that are almost certainly the wrong artifact — a debug build with DWARF or a bundle with embedded assets.

From the caller's side, these errors are usually deterministic and cheap: most implementations pre-check metadata rather than reading the payload. Codex's read_bounded_local_media compares file.metadata().len() to the cap before any bytes are read; Remotion's downloadRemoteAsset aborts on an oversized Content-Length header; AFFiNE's CloudBlobStorage.set() fails fast client-side before any network upload starts; Label Studio sums uploaded sizes (or a URL's Content-Length) before downloading. Some libraries check in multiple places: Siyuan enforces its 32 MiB HEIF cap at every entry point (convert, ImageSize, limited reads, and cache), and ECC gates at fstat, again after reading in chunks (catching files that grew mid-read or procfs-style files reporting size 0), and a third time at document-parse level. A subtler variant is Gumroad's dispute-evidence cap, which is not a constant at all — it is the remaining Stripe combined-size budget, so the effective per-file ceiling shrinks as other evidence files are attached.

Because most checks are deterministic, retrying the same input reproduces the error exactly — several records explicitly warn not to retry the same URL or file. The fix pattern is correspondingly uniform: shrink, split, re-encode, or raise the cap (where it is configurable). The knobs vary widely: some limits are hardcoded class constants (Chatbot UI's 2 MB profile image, unopim's 10 MB MAX_FILE_BYTES requiring a subclass), some are environment variables (AFFiNE_BLOB_SIZE_LIMIT, Label Studio's TASKS_MAX_FILE_SIZE, BookStack's APP_UPLOAD_LIMIT), some are php.ini pairs (October's upload_max_filesize/post_max_size), and zeroclaw layers three separate audio caps (a manager-wide global, a per-provider local_whisper cap, and the hardcoded 25 MB cloud cap) whose effective limit is the minimum that applies. Messages often embed the exact cap and actual size, which makes them self-diagnosing — though unopim's blank-size variant means filesize() failed (unreadable file), not an oversized image.

Common causes

What usually fixes it

Documented occurrences

…and 75 more across the corpus — use search.

Honest provenance: generated on 2026-09-04 from AI-assisted analysis of the linked records. See how records are made.