binary-husky/gpt_academic · error · RuntimeError

Doc2x processing timeout after maximum attempts

Error message

Doc2x processing timeout after maximum attempts

What it means

The parse-status polling loop slept 5s between polls and incremented attempt each 'processing' response; after max_attempts polls still reporting 'processing', it gives up with this timeout. Doc2x did not finish parsing the document within the client's polling budget (max_attempts × 5 seconds).

Source

Thrown at crazy_functions/pdf_fns/parse_pdf_via_doc2x.py:130

    while attempt < max_attempts:
        res = make_request(
            "GET",
            "https://v2.doc2x.noedgeai.com/api/v2/parse/status",
            headers={"Authorization": "Bearer " + doc2x_api_key},
            params=params,
            timeout=15,
        )
        res_data = doc2x_api_response_status(res)
        if res_data["status"] == "success":
            break
        elif res_data["status"] == "processing":
            time.sleep(5)
            logger.info(f"Doc2x is processing at {res_data['progress']}%")
            attempt += 1
        else:
            raise RuntimeError(f"Doc2x return an error: {res_data}")
    if attempt >= max_attempts:
        raise RuntimeError("Doc2x processing timeout after maximum attempts")

    # < ------ 第3步：提交转化 ------ >
    logger.info("Doc2x 第3步：提交转化")
    data = {
        "uid": uuid,
        "to": format,
        "formula_mode": "dollar",
        "filename": "output"
    }
    res = make_request(
        "POST",
        "https://v2.doc2x.noedgeai.com/api/v2/convert/parse",
        headers={"Authorization": "Bearer " + doc2x_api_key},
        json=data,
        timeout=15,
    )
    doc2x_api_response_status(res, uid=f"uid: {uuid}")

View on GitHub (pinned to d6bde0fa54)

Solutions

1. Increase max_attempts (or the sleep interval) for large documents — e.g. budget 1 attempt per 10 pages
2. Retry: the job often completes shortly after; Doc2x may reuse the upload via the same uid
3. Split the PDF into smaller parts and parse each separately
4. Check Doc2x status page for ongoing degradation before retrying

Example fix

# before
max_attempts = 30  # gives up too early on big files

# after
max_attempts = max(30, estimated_pages // 5)  # scale budget with document size

from pypdf import PdfReader
pages = len(PdfReader(pdf_path).pages)
max_attempts = max(30, pages // 5)  # budget scales with document size

try:
    wait_for_parse(uuid)
except RuntimeError as e:
    if 'processing timeout' in str(e):
        time.sleep(30)
        wait_for_parse(uuid, max_attempts=60)  # job usually still running server-side; extend budget
    else:
        raise

When it happens

Trigger: Large PDFs (hundreds of pages) that take minutes to parse; Doc2x under heavy load; max_attempts left at default (too small); network latency stretching each poll cycle.

Common situations: Parsing full academic theses or books; free-tier queues; the job may actually still be running server-side — the client just stopped asking.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Doc2x conversion timeout after maximum attempts
• Doc2x return an error: {res_data}
• 处理文件 {os.path.basename(fp)} 超时（{TIMEOUT_SECONDS}秒）
• 文件内容提取超时（10秒）
• 文本分割超时（5秒）

AI-assisted analysis of binary-husky/gpt_academic@d6bde0fa54 (2026-08-14). Data as JSON: /api/errors/6118db2beef70246. Report an issue: GitHub.