What causes "File exceeds the {cap // (1024 * 1024)} MB upload limit." in unslothai/unsloth?

Split or compress the document under the stated MB limit and re-upload.

unslothai/unsloth · warning · HTTPException

File exceeds the {cap // (1024 * 1024)} MB upload limit.

Error message

File exceeds the {cap // (1024 * 1024)} MB upload limit.

What it means

_persist_upload_stream() streams the upload to disk in 1 MiB blocks and enforces config.MAX_UPLOAD_BYTES; once the accumulated size exceeds the cap (checked both during streaming and after), the partially written file is removed and HTTP 413 is returned with the limit expressed in MB.

Source

Thrown at studio/backend/routes/rag.py:140

    stored_path = str(uploads / f"{uuid.uuid4().hex}{ext}")
    size = 0
    cap = config.MAX_UPLOAD_BYTES
    try:
        with open(stored_path, "wb") as out:
            while True:
                block = source.read(1 << 20)
                if not block:
                    break
                size += len(block)
                if cap and size > cap:
                    break
                out.write(block)
    except OSError:
        _remove_stored_upload(stored_path)
        raise
    if cap and size > cap:
        _remove_stored_upload(stored_path)
        raise HTTPException(
            status_code = 413,
            detail = f"File exceeds the {cap // (1024 * 1024)} MB upload limit.",
        )
    if size == 0:
        _remove_stored_upload(stored_path)
        raise HTTPException(status_code = 400, detail = empty_detail)
    return stored_path, filename


def _save_upload(file: UploadFile) -> tuple[str, str]:
    """Persist a browser upload; returns (stored_path, filename)."""
    filename = _sanitize_filename(file.filename or "document")
    return _persist_upload_stream(
        file.file,
        filename,
        empty_detail = "Uploaded file is empty.",
    )

View on GitHub (pinned to 203007d190)

Solutions

Split or compress the document under the stated MB limit and re-upload.
If large documents are expected, raise config.MAX_UPLOAD_BYTES on the backend (and any reverse-proxy body limit) and restart.
Show the limit in the UI before upload starts so users do not wait for a full transfer to learn it.

Example fix

# before
upload('huge_scan_bundle.pdf')  # 413 File exceeds the N MB upload limit
# after
# backend config
MAX_UPLOAD_BYTES = 512 * 1024 * 1024  # if 512 MB documents are supported

Defensive patterns

Strategy: validation

Validate before calling

const MAX_BYTES = await getMaxUploadLimit(); // or mirror config.MAX_UPLOAD_BYTES
if (file.size > MAX_BYTES) { notify(`File exceeds ${MAX_BYTES / 1024 / 1024} MB`); return; }

Try / catch

if (res.status === 413) { suggestSplitting(file); return; }

Prevention

Check file.size before starting the upload; a full transfer wasted on a 413 is the worst outcome.
Keep client, backend config.MAX_UPLOAD_BYTES, and reverse-proxy body limits aligned.
Show the limit next to the drop zone.

When it happens

Trigger: Uploading a document larger than config.MAX_UPLOAD_BYTES (cap // (1024*1024) MB) — e.g. a multi-hundred-MB PDF or scan set against the configured limit. The write loop stops early and deletes the partial file.

Common situations: Large scanned PDFs, concatenated transcripts, or log exports exceed the default cap; an operator raised the client-side limit but not the server's config.MAX_UPLOAD_BYTES; a proxy in front also has its own body cap that can mask this error.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/2eb543126380c436. Report an issue: GitHub.