opendataloader-project/opendataloader-pdf · error · ValueError

Unsupported format: {format!r}. Supported formats: {', '.joi

Error message

Unsupported format: {format!r}. Supported formats: {', '.join(ext_map)}

What it means

ValueError raised by the MCP convert tool when the format argument is not a key in ext_map. The accepted keys are json, text, html, markdown, markdown-with-html, markdown-with-images (the latter two are deprecated --format aliases per CLAUDE.md). The error message lists the valid set so the caller can self-correct.

Source

Thrown at python/opendataloader-pdf-mcp/src/opendataloader_pdf_mcp/server.py:89

    Returns:
        The converted content as text.
    """
    input_file = Path(input_path).expanduser().resolve()
    if not input_file.is_file():
        raise FileNotFoundError(f"Input file not found: {input_path}")

    # Determine output file extension from format
    ext_map = {
        "json": ".json",
        "text": ".txt",
        "html": ".html",
        "markdown": ".md",
        "markdown-with-html": ".md",
        "markdown-with-images": ".md",
    }
    if format not in ext_map:
        raise ValueError(
            f"Unsupported format: {format!r}. "
            f"Supported formats: {', '.join(ext_map)}"
        )
    ext = ext_map[format]

    with tempfile.TemporaryDirectory() as tmp_dir:
        kwargs: dict[str, Any] = {
            "input_path": str(input_file),
            "output_dir": tmp_dir,
            "format": format,
            "quiet": True,
        }

        # Only pass non-default values
        if password is not None:
            kwargs["password"] = password
        if pages is not None:
            kwargs["pages"] = pages

View on GitHub (pinned to a7789b8e77)

Solutions

1. Use one of the listed formats: json, text, html, markdown (preferred); markdown-with-html / markdown-with-images still accepted but deprecated.
2. For HTML-in-markdown use format='markdown' plus the markdown-with-html flag, not a made-up format name.
3. If you need PDF output, note that tagged-pdf is an OUTPUT format handled separately — check the CLI options.json for the current set.
4. Validate the format against the tool's documented enum before calling.

Example fix

# before: invented format
convert(input_path=pdf, format="pdf")  # -> ValueError
# after: valid format; HTML-in-markdown via the modifier flag
convert(input_path=pdf, format="markdown", markdown_with_html=True)

SUPPORTED_FORMATS = {"json", "text", "html", "markdown", "markdown-with-html", "markdown-with-images"}

def validate_format(fmt: str) -> str:
    if fmt not in SUPPORTED_FORMATS:
        raise ValueError(f"Unsupported format: {fmt!r}. Use one of {sorted(SUPPORTED_FORMATS)}")
    return fmt

def is_supported_format(fmt: str) -> bool:
    return fmt in {"json", "text", "html", "markdown", "markdown-with-html", "markdown-with-images"}

try:
    result = convert(input_path=path, format=fmt)
except ValueError as e:
    if "Unsupported format" in str(e):
        return {"error": str(e), "formats": sorted(SUPPORTED_FORMATS)}
    raise

When it happens

Trigger: Calling the MCP convert tool with a format value outside the ext_map keys: e.g. 'pdf', 'csv', 'xml', 'markdown_html' (underscore instead of hyphen), or a typo like 'mar kdown'.

Common situations: An LLM/client invents a format not in the schema. A caller uses the deprecated markdown-with-images form without realizing it still works. Locale/normalization turns a hyphen into another character. A caller passes the image-output mode (off|embedded|external) into the format field by mistake.

Related errors

• Input file not found: {input_path}
• Option --format requires at least one value. Supported value
• Unsupported format '%s'. Supported values: json, text, html,
• Conversion completed but no output file was generated.
• Conversion completed but no '{ext}' output file was generate

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/dcdfdccda080a3a5. Report an issue: GitHub.