datawhalechina/hello-agents · error · ValueError

Unsupported document_ingestion_mode: {mode}

Error message

Unsupported document_ingestion_mode: {mode}

What it means

`ingest_document` validates the `mode` argument (default 'auto') after strip+lowercase against {'auto', 'text_only', 'vision_fallback'} and raises ValueError on anything else. mode selects how the PDF is parsed: automatic text extraction, text-only, or vision-LLM fallback.

Source

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

def ingest_input_document(
    data_path: str | Path,
    *,
    run_dir: str | Path,
    data_dir: str | Path,
    logs_dir: str | Path,
    mode: str = "auto",
    max_pdf_pages: int = 20,
    max_candidate_tables: int = 5,
    selected_table_id: str | None = None,
) -> IngestionResult:
    started_at = time.perf_counter()
    source_path = Path(data_path).resolve()
    data_dir = Path(data_dir)
    logs_dir = Path(logs_dir)
    normalized_mode = str(mode or "auto").strip().lower()
    if normalized_mode not in {"auto", "text_only", "vision_fallback"}:
        raise ValueError(f"Unsupported document_ingestion_mode: {mode}")

    log_path = logs_dir / "document_ingestion.json"
    if source_path.suffix.lower() in SUPPORTED_TABULAR_SUFFIXES:
        result = IngestionResult(
            input_kind="tabular",
            status="not_needed",
            summary="输入文件已经是结构化表格，跳过文档解析阶段。",
            normalized_data_path=source_path,
            duration_ms=_elapsed_ms(started_at),
            log_path=log_path,
            candidate_table_count=0,
            pdf_multi_table_mode=False,
        )
        payload = {
            "input_kind": result.input_kind,
            "status": result.status,
            "summary": result.summary,
            "normalized_data_path": result.normalized_data_path.as_posix(),

View on GitHub (pinned to 606a07d341)

Solutions

1. Use exactly 'auto', 'text_only', or 'vision_fallback' (case-insensitive, whitespace trimmed).
2. Note 'vision_fallback' itself is accepted here but rejected later at document_ingestion.py:333 — prefer 'auto' or 'text_only'.
3. Omit mode entirely to get 'auto' behavior.
4. Check SUPPORTED_DOCUMENT_SUFFIXES / SUPPORTED_TABULAR_SUFFIXES handling before calling so the mode check is reached with a document file.

INGESTION_MODES = {"auto", "text_only", "vision_fallback"}

def validate_ingestion_mode(mode: str | None) -> str:
    normalized = str(mode or "auto").strip().lower()
    if normalized not in INGESTION_MODES:
        raise ValueError(f"mode must be one of {sorted(INGESTION_MODES)}, got {mode!r}")
    return normalized

from typing import Literal, TypeGuard

IngestionMode = Literal["auto", "text_only", "vision_fallback"]

def is_ingestion_mode(value: object) -> TypeGuard[IngestionMode]:
    return isinstance(value, str) and value.strip().lower() in {"auto", "text_only", "vision_fallback"}

try:
    result = ingest_document(path, data_dir, logs_dir, mode=mode)
except ValueError as e:
    if "document_ingestion_mode" in str(e):
        result = ingest_document(path, data_dir, logs_dir, mode="auto")
    else:
        raise

When it happens

Trigger: Calling ingest_document with mode='text', 'vision', 'ocr', or similar partial names; passing None is coerced to 'auto' safely (`str(mode or 'auto')`), but wrong strings fail; mode names taken from an older/newer version of the API.

Common situations: Client code guessing mode names, config files copied from other projects, or docs drift after the mode set changed.

Related errors

• Unsupported latency_mode: {latency_mode}
• Unsupported vision_review_mode: {vision_review_mode}
• Unsupported quality_mode: {quality_mode}
• 不支持的任务类型: {task_type}
• Unsupported data file format: {data_path.suffix}

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