opendatalab/MinerU · error · ValueError

Unsupported header/footer label: {label}

Error message

Unsupported header/footer label: {label}

What it means

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.

Source

Thrown at mineru/model/layout/pp_doclayoutv2.py:1204

    @staticmethod
    def _set_box_label(box: Dict, label: str) -> None:
        """统一同步设置 layout 检测框的标签名和类别编号。"""
        if label not in PP_DOCLAYOUT_V2_LABEL_TO_ID:
            raise ValueError(f"Unsupported PP-DocLayoutV2 label: {label}")
        box["label"] = label
        box["cls_id"] = PP_DOCLAYOUT_V2_LABEL_TO_ID[label]

    @staticmethod
    def _set_formula_label(box: Dict, label: str) -> None:
        if label not in {"inline_formula", "display_formula"}:
            raise ValueError(f"Unsupported formula label: {label}")
        PPDocLayoutV2LayoutModel._set_box_label(box, label)

    @staticmethod
    def _set_header_footer_label(box: Dict, label: str) -> None:
        """同步设置页眉/页脚相关标签及其类别编号。"""
        if label not in {"footer", "footer_image", "header", "header_image"}:
            raise ValueError(f"Unsupported header/footer label: {label}")
        PPDocLayoutV2LayoutModel._set_box_label(box, label)

    @staticmethod
    def _set_footnote_label(box: Dict) -> None:
        """同步设置 page footnote 标签及其类别编号。"""
        PPDocLayoutV2LayoutModel._set_box_label(box, "footnote")

    @classmethod
    def _reclassify_header_footer_by_page_half(
        cls,
        boxes: List[Dict],
        image_size: Optional[Tuple[int, int]],
    ) -> List[Dict]:
        """按页面上下半区重新校正页眉/页脚锚点，避免跨半页误触发边界规则。"""
        if image_size is None:
            return boxes

        page_height = float(image_size[0])

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Pass one of: 'header', 'header_image', 'footer', 'footer_image'.
2. Use _set_footnote_label(box) for footnotes and _set_box_label(box, 'number') for page numbers.
3. Check spelling (underscore, not hyphen) when constructing the label string.

Example fix

# before
_set_header_footer_label(box, 'header-footer')  # ValueError

# after
_set_header_footer_label(box, 'header')  # or 'header_image' / 'footer' / 'footer_image'

HEADER_FOOTER_LABELS = {'footer', 'footer_image', 'header', 'header_image'}

def set_header_footer_label(box: dict, label: str) -> None:
    if label not in HEADER_FOOTER_LABELS:
        raise ValueError(f'expected one of {sorted(HEADER_FOOTER_LABELS)}, got {label!r}')
    PPDocLayoutV2LayoutModel._set_header_footer_label(box, label)

def is_header_footer_label(label: str) -> bool:
    return label in {'footer', 'footer_image', 'header', 'header_image'}

When it happens

Trigger: _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.

Common situations: 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.

Related errors

• Unsupported PP-DocLayoutV2 label: {label}
• Unsupported formula label: {label}
• effort must be "medium" or "high"
• pdf_bytes_list, image_writer_list, and lang_list must have t
• Unsupported lmdeploy device type: {device_type}

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/03f630e42d1faa76. Report an issue: GitHub.