{"record":{"id":"03f630e42d1faa76","repo":"opendatalab/MinerU","slug":"unsupported-header-footer-label-label","errorCode":null,"errorMessage":"Unsupported header/footer label: {label}","messagePattern":"Unsupported header/footer label: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mineru/model/layout/pp_doclayoutv2.py","lineNumber":1204,"sourceCode":"    @staticmethod\n    def _set_box_label(box: Dict, label: str) -> None:\n        \"\"\"统一同步设置 layout 检测框的标签名和类别编号。\"\"\"\n        if label not in PP_DOCLAYOUT_V2_LABEL_TO_ID:\n            raise ValueError(f\"Unsupported PP-DocLayoutV2 label: {label}\")\n        box[\"label\"] = label\n        box[\"cls_id\"] = PP_DOCLAYOUT_V2_LABEL_TO_ID[label]\n\n    @staticmethod\n    def _set_formula_label(box: Dict, label: str) -> None:\n        if label not in {\"inline_formula\", \"display_formula\"}:\n            raise ValueError(f\"Unsupported formula label: {label}\")\n        PPDocLayoutV2LayoutModel._set_box_label(box, label)\n\n    @staticmethod\n    def _set_header_footer_label(box: Dict, label: str) -> None:\n        \"\"\"同步设置页眉/页脚相关标签及其类别编号。\"\"\"\n        if label not in {\"footer\", \"footer_image\", \"header\", \"header_image\"}:\n            raise ValueError(f\"Unsupported header/footer label: {label}\")\n        PPDocLayoutV2LayoutModel._set_box_label(box, label)\n\n    @staticmethod\n    def _set_footnote_label(box: Dict) -> None:\n        \"\"\"同步设置 page footnote 标签及其类别编号。\"\"\"\n        PPDocLayoutV2LayoutModel._set_box_label(box, \"footnote\")\n\n    @classmethod\n    def _reclassify_header_footer_by_page_half(\n        cls,\n        boxes: List[Dict],\n        image_size: Optional[Tuple[int, int]],\n    ) -> List[Dict]:\n        \"\"\"按页面上下半区重新校正页眉/页脚锚点，避免跨半页误触发边界规则。\"\"\"\n        if image_size is None:\n            return boxes\n\n        page_height = float(image_size[0])","sourceCodeStart":1186,"sourceCodeEnd":1222,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/model/layout/pp_doclayoutv2.py#L1186-L1222","documentation":"ValueError raised by _set_header_footer_label when label is not one of 'footer', 'footer_image', 'header', 'header_image'. The helper backs _reclassify_header_footer_by_page_half, which splits detected boxes into text vs image header/footer variants, and only those four synced label/id pairs are legal.","triggerScenarios":"_set_header_footer_label(box, 'header-footer') (hyphen typo), 'page_number', or 'footnote' — footnote has its own helper _set_footnote_label; also 'number' (page number, cls 16) misrouted here.","commonSituations":"Custom header/footer post-processing using invented names; mixing up page-number ('number') or footnote handling with header/footer reclassification; vocab mismatches after model upgrades.","solutions":["Pass one of: 'header', 'header_image', 'footer', 'footer_image'.","Use _set_footnote_label(box) for footnotes and _set_box_label(box, 'number') for page numbers.","Check spelling (underscore, not hyphen) when constructing the label string."],"exampleFix":"# before\n_set_header_footer_label(box, 'header-footer')  # ValueError\n\n# after\n_set_header_footer_label(box, 'header')  # or 'header_image' / 'footer' / 'footer_image'","handlingStrategy":"validation","validationCode":"HEADER_FOOTER_LABELS = {'footer', 'footer_image', 'header', 'header_image'}\n\ndef set_header_footer_label(box: dict, label: str) -> None:\n    if label not in HEADER_FOOTER_LABELS:\n        raise ValueError(f'expected one of {sorted(HEADER_FOOTER_LABELS)}, got {label!r}')\n    PPDocLayoutV2LayoutModel._set_header_footer_label(box, label)","typeGuard":"def is_header_footer_label(label: str) -> bool:\n    return label in {'footer', 'footer_image', 'header', 'header_image'}","tryCatchPattern":null,"preventionTips":["Use underscores ('header_image'), never hyphens, in these label strings.","Use _set_footnote_label for footnotes and _set_box_label(box, 'number') for page numbers.","Centralize label constants instead of building strings ad hoc at call sites."],"tags":["layout-model","labels","validation","header-footer"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}