What causes "Doc2x return an error: {res_data}" in binary-husky/gpt_academic?

Inspect res_data in the message — it typically contains a 'msg'/'message' explaining the server-side failure

binary-husky/gpt_academic · error · RuntimeError

Doc2x return an error: {res_data}

Error message

Doc2x return an error: {res_data}

What it means

During the parse-status polling loop, the response passed status validation but its data.status field is neither 'success' nor 'processing' — an unexpected terminal state (e.g. 'failed' or 'error'). The whole data dict is embedded in the message, which will be large but shows the failure reason from Doc2x.

Source

Thrown at crazy_functions/pdf_fns/parse_pdf_via_doc2x.py:128

    max_attempts = 60
    attempt = 0
    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,
    )

View on GitHub (pinned to d6bde0fa54)

Solutions

Inspect res_data in the message — it typically contains a 'msg'/'message' explaining the server-side failure
Retry once: transient server-side parse failures are common; if it fails identically, the PDF is the problem
Test the same PDF with a smaller/simpler document to isolate content-specific failures
For scanned PDFs, OCR first, or switch to the GROBID-based parsing plugin instead of Doc2x

Defensive patterns

Strategy: try-catch

Validate before calling

def parse_status_ok(res_data: dict) -> bool:
    return res_data.get('status') in ('success', 'processing')

Try / catch

try:
    poll_parse_status(uuid)
except RuntimeError as e:
    if 'Doc2x return an error' in str(e) and 'failed' in str(e).lower():
        raise RuntimeError('Doc2x could not parse this PDF (server-side); try another parser') from e
    raise

Prevention

Treat unknown data.status values as terminal failures immediately with full payload logging
Retry once — transient server-side failures do occur; identical second failure means bad input
Keep the GROBID plugin as an alternate parsing path for rejected files

When it happens

Trigger: Doc2x fails to parse the uploaded PDF server-side (data.status == 'failed'); API adds a new status value the client does not handle; the parse job is cancelled server-side.

Common situations: Scanned or complex PDFs that Doc2x's engine rejects mid-processing; very large files timing out server-side; intermittent service degradation.

Related errors

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