opendatalab/MinerU · error · Exception

Unknown file suffix: {file_suffix}

Error message

Unknown file suffix: {file_suffix}

What it means

Generic Exception from read_fn(): after reading the file bytes, the suffix (provided explicitly or guessed from magic bytes via guess_suffix_by_bytes) matched neither image_suffixes nor pdf_suffixes+office_suffixes, so mineru cannot convert the input to a PDF parse stream.

Source

Thrown at mineru/cli/common.py:183

        if effective_stem != stem:
            renamed.append((stem, effective_stem))

    return unique_stems, renamed


def read_fn(path, file_suffix: str | None = None):
    if not isinstance(path, Path):
        path = Path(path)
    with open(str(path), "rb") as input_file:
        file_bytes = input_file.read()
        if file_suffix is None:
            file_suffix = guess_suffix_by_bytes(file_bytes, path)
        if file_suffix in image_suffixes:
            return images_bytes_to_pdf_bytes(file_bytes)
        elif file_suffix in pdf_suffixes + office_suffixes:
            return file_bytes
        else:
            raise Exception(f"Unknown file suffix: {file_suffix}")


def prepare_env(output_dir, pdf_file_name, parse_method):
    local_md_dir = str(os.path.join(output_dir, pdf_file_name, parse_method))
    local_image_dir = os.path.join(str(local_md_dir), "images")
    os.makedirs(local_image_dir, exist_ok=True)
    os.makedirs(local_md_dir, exist_ok=True)
    return local_image_dir, local_md_dir


def convert_pdf_bytes_to_bytes(pdf_bytes, start_page_id=0, end_page_id=None):
    try:
        rebuilt_pdf_bytes = rewrite_pdf_bytes_with_pdfium(
            pdf_bytes,
            start_page_id=start_page_id,
            end_page_id=end_page_id,
        )
        if rebuilt_pdf_bytes:

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Convert the input to a supported format first (PDF, common image formats, DOCX/PPTX/XLSX)
2. Pass the correct file_suffix explicitly if guessing fails and the format is supported
3. Filter inputs before batch runs: only accept files with supported suffixes/magic bytes
4. For TIFF/BMP, convert to PNG/JPEG or wrap into a PDF before parsing

Example fix

# before
read_fn(Path('notes.txt'))

# after
# convert to PDF first, e.g. with libreoffice or img2pdf, then:
read_fn(Path('notes.pdf'))

from pathlib import Path

SUPPORTED_SUFFIXES = {".pdf", ".png", ".jpg", ".jpeg", ".bmp", ".docx", ".pptx", ".xlsx"}  # align with your mineru version

def acceptable(p: Path) -> bool:
    return p.suffix.lower() in SUPPORTED_SUFFIXES

files = [p for p in Path(src).iterdir() if acceptable(p)]

def is_supported_document(path: str) -> bool:
    from pathlib import Path
    return Path(path).suffix.lower() in {".pdf", ".png", ".jpg", ".jpeg", ".docx", ".pptx", ".xlsx"}

try:
    pdf_bytes = read_fn(path)
except Exception as e:
    if "Unknown file suffix" in str(e):
        path = convert_to_pdf(path)  # e.g. img2pdf / libreoffice, then retry
        pdf_bytes = read_fn(path)
    else:
        raise

When it happens

Trigger: Feeding files whose true type is not PDF/image/office — e.g. .txt, .html, .csv, .epub, or a mislabeled file where content sniffing fails; passing an explicit file_suffix kwarg with an unsupported value like 'xyz' or '.tiff' when tiff is not in image_suffixes.

Common situations: Directory sweeps that pick up stray non-document files; users renaming files to .pdf hoping conversion happens; unusual image formats (e.g. TIFF/BMP) not in the supported suffix list; empty or truncated downloads whose magic bytes are gone.

Related errors

• Input path does not exist: {path}
• Unsupported input file type: {path.name}
• Input path must be a file or directory: {path}
• No supported files found in directory: {path}
• Unsupported office suffix: {file_suffix}

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