datawhalechina/hello-agents · warning · ValueError

V1 暂不支持 vision_fallback，请先使用文本型 PDF 或手动裁剪目标表格。

Error message

V1 暂不支持 vision_fallback，请先使用文本型 PDF 或手动裁剪目标表格。

What it means

A deliberate scope-limit guard: if the input passes the document-suffix check but mode=='vision_fallback', ingest_document raises ValueError saying V1 does not support vision_fallback and the user should supply a text-based PDF or manually crop the target table. I.e. the mode value is validated (216) but intentionally unimplemented in V1.

Source

Thrown at Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/document_ingestion.py:333

        payload = {
            "input_kind": result.input_kind,
            "status": result.status,
            "summary": result.summary,
            "normalized_data_path": result.normalized_data_path.as_posix(),
            "duration_ms": result.duration_ms,
            "candidate_table_count": 0,
            "pdf_multi_table_mode": False,
            "mode": normalized_mode,
        }
        log_path.parent.mkdir(parents=True, exist_ok=True)
        log_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
        return result

    if source_path.suffix.lower() not in SUPPORTED_DOCUMENT_SUFFIXES:
        raise ValueError(f"Unsupported input file format: {source_path.suffix}")

    if normalized_mode == "vision_fallback":
        raise ValueError("V1 暂不支持 vision_fallback，请先使用文本型 PDF 或手动裁剪目标表格。")

    extracted_tables_dir = data_dir / "extracted_tables"
    cleaned_data_path = (data_dir / "cleaned_data.csv").resolve()
    parsed_document_path = (data_dir / "parsed_document.json").resolve()

    full_text, records = _extract_pdf_payload(
        source_path,
        max_pdf_pages=max_pdf_pages,
        max_candidate_tables=max_candidate_tables,
        extracted_tables_dir=extracted_tables_dir,
    )
    background_literature_context = _extract_background_context(full_text)
    requested_table_id = str(selected_table_id or "").strip()
    requested_record = None
    if requested_table_id:
        requested_record = next((record for record in records if record.table_id == requested_table_id), None)
        if requested_record is None:
            raise ValueError(

View on GitHub (pinned to 606a07d341)

Solutions

  1. Use mode='auto' (or 'text_only') with a text-based PDF — re-export or OCR the source to embed a text layer.
  2. Manually crop the target table (screenshot/Excel) and supply it as .csv/.xlsx, which takes the tabular path.
  3. OCR the PDF (e.g. ocrmypdf -l eng input.pdf output.pdf) so text extraction works.
  4. Track upstream releases for V2 vision_fallback support.
Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
from pathlib import Path

def ocr_layer_present(pdf_path: Path) -> bool:
    """Heuristic: a text-based PDF extracts characters via pdfplumber."""
    import pdfplumber
    with pdfplumber.open(pdf_path) as pdf:
        return any((page.extract_text() or "").strip() for page in pdf.pages[:3])

if not ocr_layer_present(Path(pdf_path)):
    print("Scanned PDF: run OCR (ocrmypdf) first; vision_fallback is unsupported in V1")

Try / catch

try:
    result = ingest_document(path, data_dir, logs_dir, mode="vision_fallback")
except ValueError as e:
    if "vision_fallback" in str(e):
        # fall back: OCR the file, then re-ingest in text mode
        subprocess.run(["ocrmypdf", str(path), str(path)], check=True)
        result = ingest_document(path, data_dir, logs_dir, mode="auto")
    else:
        raise

Prevention

When it happens

Trigger: Explicitly requesting document_ingestion_mode='vision_fallback' — typically for scanned/image-only PDFs where pdfplumber's text extraction yields nothing usable.

Common situations: Users with scanned papers or image-based PDF tables hitting the text-extraction limitation and reaching for the vision mode; client defaults that try vision_fallback automatically on failure.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/04e2825766fc9381. Report an issue: GitHub.