agentscope-ai/agentscope · error · ValueError

The table_format must be one of 'markdown' or 'json', got {t

Error message

The table_format must be one of 'markdown' or 'json', got {table_format!r}.

What it means

ExcelParser only accepts table_format of 'markdown' or 'json'; any other value is rejected in __init__ with a ValueError showing the invalid value.

Source

Thrown at src/agentscope/rag/_parser/_excel.py:202

            include_cell_coordinates (`bool`, defaults to ``False``):
                Whether to include cell coordinates (e.g. ``[A1]``) in
                the rendered table.
            include_image (`bool`, defaults to ``False``):
                Whether to extract and include embedded images.
                Requires ``openpyxl``.
            separate_sheet (`bool`, defaults to ``False``):
                If ``True``, images and table text from different
                sheets are never combined into the same section.
            table_format (`Literal["markdown", "json"]``, defaults to
                ``"markdown"``):
                How to render tables.

        Raises:
            `ValueError`: If ``table_format`` is not ``"markdown"``
                or ``"json"``.
        """
        if table_format not in ("markdown", "json"):
            raise ValueError(
                "The table_format must be one of 'markdown' or 'json', "
                f"got {table_format!r}.",
            )
        self.include_sheet_names = include_sheet_names
        self.include_cell_coordinates = include_cell_coordinates
        self.include_image = include_image
        self.separate_sheet = separate_sheet
        self.table_format = table_format

    async def parse(
        self,
        file: bytes | str,
        filename: str,
    ) -> list[Section]:
        """Parse an Excel file into a list of :class:`Section` objects.

        Args:
            file (`bytes | str`):

View on GitHub (pinned to e90f1c7592)

Solutions

Use exactly 'markdown' or 'json' (lowercase)
Normalize config input: fmt = fmt.lower() and map 'md'->'markdown' before constructing

Example fix

# before
parser = ExcelParser(table_format='md')

# after
parser = ExcelParser(table_format='markdown')

Defensive patterns

Strategy: validation

Validate before calling

table_format = {'md': 'markdown'}.get(table_format, table_format)
assert table_format in ('markdown', 'json')

Type guard

def is_table_format(v: str) -> bool:
    return v in ('markdown', 'json')

Prevention

Use a Literal['markdown','json'] type in your config models
Normalize abbreviations at config load

When it happens

Trigger: Constructing ExcelParser(table_format='csv') or 'md'/'Markdown' (case-sensitive) or 'html'.

Common situations: Passing 'md' as an abbreviation; case mismatch from config files; copying format strings from a different parser/library.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/9e1f21c150838140. Report an issue: GitHub.