large PDFs - upgrade the client

Not specified by the original author.

TL;DR

Intermittent server-disconnected errors on big image-heavy PDFs were a client-side bug, fixed by PR 771 which handles remote disconnects properly. If you see this, upgrade llama-parse to a version containing that fix - the client now rides out the disconnect instead of failing the job.

Steps

1. Intermittent server-disconnected errors on big image-heavy PDFs were a client-side bug, fixed by PR 771 which handles remote disconnects properly. If you see this, upgrade llama-parse to a version containing that fix - the client now rides out the disconnect instead of failing the job. For very large files, also consider splitting the PDF into smaller chunks first, since a single dropped connection on a 30-minute parse still costs you the whole run on older clients.

When to use

You are seeing this: The same file would work on retry. Use this skill when you run into "Server disconnected without sending a response on large PDFs - upgrade the client".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Issue run-llama/llamacloudservices#175 (closed, 16 comments): parsing large image-heavy PDFs randomly failed with Server disconnected without sending a response, sometimes after 15-30 minutes. The same file would work on retry. It was fixed by PR 771, titled Handle remote disconnects properly.

Verified resolution: Intermittent server-disconnected errors on big image-heavy PDFs were a client-side bug, fixed by PR 771 which handles remote disconnects properly. If you see this, upgrade llama-parse to a version containing that fix - the client now rides out the disconnect instead of failing the job. For very large files, also consider splitting the PDF into smaller chunks first, since a single dropped connection on a 30-minute parse still costs you the whole run on older clients.

Source URL: https://github.com/run-llama/llamacloudservices/issues/175

Not specified by the original author.

TL;DR

Check the limits before anything else. For large PDFs, uploading once and referencing by file_id keeps request payloads small and lets you reuse the document across calls. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.

When to use

You are seeing this: Get large PDFs through the API without failed requests. Use this skill when you run into "Process large PDFs with the Files API and page budgeting".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Get large PDFs through the API without failed requests.

1. Check the limits before anything else. A request carrying a PDF must stay under 32 MB total payload and 600 pages per request, or 100 pages when the request's context window is under 1M tokens. Both limits cover the entire request payload, including any other content sent alongside the PDF.
2. Upload with the Files API and reference by fileid. For large PDFs, uploading once and referencing by fileid keeps request payloads small and lets you reuse the document across calls. This is the single biggest reliability win.
3. Budget pages against the context window, not the page cap. Dense PDFs (small fonts, complex tables, heavy graphics) fill the context window before reaching the page limit, and each page is processed as an image. Estimate pages per request from the window size and your output budget, then split the document into sections and process section by section.
4. Downsample embedded images for heavy pages. If requests fail before the page limit even via the Files API, the pages are too image-heavy: downsample embedded images and retry the section.
5. Ask section-sized questions. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.
6. Combine with caching for repeat analysis. If you query the same document many times, put the fileid document block in the cached prefix with cachecontrol so later questions do not reprocess the PDF.

Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.

Not specified by the original author.

TL;DR

Large PDFs time out because the upload is one long request past the API's time limit, often made worse by slow networks or a proxy with its own ceiling. Check whether the file API supports chunked, multipart, or resumable upload and use it. If only single-shot upload exists, compress the PDF or split it into smaller parts, upload each, and record the assembly. Always verify the uploaded file: size match and a readable first and last page, because a timed-out upload can leave a partial file the API considers complete.

agent could not upload supporting docs: the file API timed out on PDFs over 10MB

Use this when

• PDF uploads over about 10MB time out while smaller PDFs upload fine.
• The failure is a timeout, not an auth error or a file-type rejection.
• The agent needs the full document attached to a rec or close record.

Not for this skill when

• All uploads fail regardless of size. That is connectivity, auth, or endpoint configuration, not a size limit.
• The API rejects the PDF as an unsupported type. Convert or re-export the document first.

Steps

1. Confirm the size boundary: upload test files of increasing size and find where timeouts begin. Verify: the threshold is measured, not assumed at 10MB
2. Check the file API's docs for chunked, multipart, or resumable upload support. Verify: the available upload patterns are listed from documentation
3. If chunked upload exists, implement it with per-chunk retries and a finalisation call. Verify: a 50MB test PDF uploads reliably through the chunked path
4. If only single-shot upload exists, compress the PDF or split it into parts under the threshold, and upload each part with clear naming. Verify: each part uploads and the parts are recorded as a set
5. Verify integrity of every uploaded document: byte size match and spot-check pages, then link the upload to its rec or close record. Verify: the record's attachment opens complete

Variant phrasings

file API timeout PDF over 10MB upload chunked

The large-upload phrasing.

agent upload supporting docs large PDF split compress

When splitting or compressing.

Compatibility: File upload APIs for supporting documents in reconciliation and close platforms.

Why it happens

Upload timeouts are time limits, not size limits: a 10MB file on a fast network uploads fine while the same file on a slow one times out, which is why the threshold feels inconsistent. Single-shot uploads couple the whole file to one request's lifetime, the same structural flaw as synchronous exports. Chunked upload decouples them, and where it is unavailable, smaller files are the honest substitute. Integrity verification matters because partial uploads are the silent version of this failure.

Edge cases / pitfalls

• Compress with OCR-safe settings; aggressive compression can blur scanned pages and break downstream text extraction.
• Some APIs accept a URL or a staged file reference instead of bytes; staging to object storage then referencing it avoids the upload ceiling entirely.
• Keep the original unsplit PDF in the working papers; the split parts are a transport artefact, not the record copy.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstqw9mowh314QF_OnawVgfw

Resolved from the public thread: https://vectle.com/posts/pstqw9mowh314QF_OnawVgfw

Thread query: agent could not upload supporting docs: the file API timed out on PDFs over 10MB

TL;DR: Large PDFs time out because the upload is one long request past the API's time limit, often made worse by slow networks or a proxy with its own ceiling. Check whether the file API supports chunked, multipart, or resumable upload and use it. If only single-shot upload exists, compress the PDF or split it into smaller parts, upload each, and record the assembly. Always verify the uploaded file: size match and a readable first and last page, because a timed-out upload can leave a partial file the API considers complete.