{"record":{"id":"d7379a5136aaeebd","repo":"PaddlePaddle/PaddleOCR","slug":"malformed-document-parsing-result-payload-e","errorCode":null,"errorMessage":"Malformed document parsing result payload: {e}","messagePattern":"Malformed document parsing result payload: (.+?)","errorType":"exception","errorClass":"ResultParseError","httpStatus":null,"severity":"error","filePath":"paddleocr/_api_client/_poller.py","lineNumber":152,"sourceCode":"                pages.append(\n                    DocParsingPage(\n                        markdown_text=markdown[\"text\"],\n                        markdown_images=markdown.get(\"images\", {}),\n                        output_images=item.get(\"outputImages\", {}),\n                        pruned_result=item.get(\"prunedResult\"),\n                        input_image_url=item.get(\"inputImage\"),\n                        exports=item.get(\"exports\", {}),\n                        markdown=markdown,\n                        raw=item,\n                    )\n                )\n        return DocParsingResult(\n            job_id=job_id,\n            pages=pages,\n            data_info=data_info,\n        )\n    except (KeyError, TypeError) as e:\n        raise ResultParseError(f\"Malformed document parsing result payload: {e}\") from e\n","sourceCodeStart":134,"sourceCodeEnd":153,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_api_client/_poller.py#L134-L153","documentation":"ResultParseError raised while converting downloaded JSONL into a DocParsingResult (PP-StructureV3 / document parsing): a KeyError or TypeError hit the expected structure ('result', 'layoutParsingResults', per-item 'markdown', 'markdown.images', 'exports', etc.). The chained exception identifies the exact missing key or wrong type.","triggerScenarios":"parse_doc_parsing_result(job_id, jsonl_data) raises when a line lacks 'result', 'layoutParsingResults' is missing/not a list, an item lacks 'markdown', or markdown/images entries have unexpected types. Happens when the server's document-parsing schema differs from the client's expectations or a plain-OCR result is fed to the document parser.","commonSituations":"Version skew between client and PaddleOCR server on the PP-StructureV3 result format; calling the doc-parsing parse path on a plain OCR job's output; server returning an error line inside the JSONL; renamed fields (e.g. markdown.images key changes) after a server upgrade.","solutions":["Dump the raw JSONL lines and verify each expected key ('result', 'layoutParsingResults', item['markdown']) exists before parsing","Match client version to server version; pin the version pair that works","Ensure the job was actually a document-parsing job — use the OCR path for OCR jobs","If the schema legitimately changed, extend the parser locally or open an issue with the raw payload attached"],"exampleFix":"# before\nresult = parse_doc_parsing_result(job_id, jsonl)  # KeyError('markdown')\n\n# after\nfor line in jsonl:\n    item = line['result']['layoutParsingResults'][0]\n    assert 'markdown' in item, f\"unexpected schema: {sorted(item)}\"\nresult = parse_doc_parsing_result(job_id, jsonl)","handlingStrategy":"try-catch","validationCode":"def looks_like_doc_result(jsonl_data) -> bool:\n    return bool(jsonl_data) and all(\n        isinstance(l, dict) and isinstance(l.get('result'), dict)\n        and isinstance(l['result'].get('layoutParsingResults'), list)\n        for l in jsonl_data\n    )","typeGuard":"def is_doc_parsing_payload(obj: object) -> bool:\n    if not isinstance(obj, list) or not obj:\n        return False\n    r = obj[0].get('result') if isinstance(obj[0], dict) else None\n    items = r.get('layoutParsingResults') if isinstance(r, dict) else None\n    return bool(items) and isinstance(items[0], dict) and 'markdown' in items[0]","tryCatchPattern":"try:\n    result = parse_doc_parsing_result(job_id, jsonl_data)\nexcept ResultParseError as e:\n    logger.error(\"doc result schema mismatch for %s: %s\", job_id, e)\n    raise","preventionTips":["Pin the server version that produced the schema your code assumes","Keep the raw JSONL alongside parsed outputs in production for auditing","Unit-test the parser against a known-good fixture after every server upgrade"],"tags":["parsing","schema-mismatch","document-parsing"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}