pandas-dev/pandas · error · ValueError

Cannot override builtin dialect.

Error message

Cannot override builtin dialect.

What it means

Raised by the csv_dialect context manager (contexts.py:96-128, a pandas._testing helper) when you try to register a CSV dialect whose name collides with one of Python's builtin dialects: 'excel', 'excel-tab', or 'unix'. The guard (contexts.py:119-122) protects csv.register_dialect from shadowing builtins, since overriding them can corrupt all subsequent CSV parsing.

Source

Thrown at pandas/_testing/contexts.py:122

    name : str
        The name of the dialect.
    kwargs : mapping
        The parameters for the dialect.

    Raises
    ------
    ValueError : the name of the dialect conflicts with a builtin one.

    See Also
    --------
    csv : Python's CSV library.
    """
    import csv

    _BUILTIN_DIALECTS = {"excel", "excel-tab", "unix"}

    if name in _BUILTIN_DIALECTS:
        raise ValueError("Cannot override builtin dialect.")

    csv.register_dialect(name, **kwargs)
    try:
        yield
    finally:
        csv.unregister_dialect(name)


def raises_chained_assignment_error(
    extra_warnings: tuple[type[Warning], ...] = (),
    extra_match: tuple[str | None, ...] = (),
) -> AbstractContextManager:
    from pandas._testing import assert_produces_warning

    if CHAINED_WARNING_DISABLED:
        if not extra_warnings:
            from contextlib import nullcontext

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Choose a non-builtin dialect name, e.g. 'my_excel', 'test_dialect', 'pandas_test'.
2. Check the name against {'excel', 'excel-tab', 'unix'} before passing it in.
3. If you genuinely need excel-like behavior, use the builtin 'excel' dialect directly without registering a new one.

Example fix

# before
with tm.csv_dialect('excel', delimiter=';'):
    ...

# after
with tm.csv_dialect('my_excel', delimiter=';'):
    ...

BUILTIN = {'excel', 'excel-tab', 'unix'}
name = get_dialect_name()
if name in BUILTIN:
    raise ValueError(f'{name} is a builtin CSV dialect')
with tm.csv_dialect(name, **kwargs):
    ...

When it happens

Trigger: Entering `with tm.csv_dialect('excel', **kwargs):` or tm.csv_dialect('excel-tab', ...) or tm.csv_dialect('unix', ...). The name is checked against _BUILTIN_DIALECTS before csv.register_dialect is called.

Common situations: Writing a CSV-parsing test and picking a short, 'obvious' dialect name that happens to be a builtin; generic test-fixture code that auto-names dialects and occasionally lands on 'excel'.

Related errors

• check_like must be False if check_index is False
• Value must be an instance of {type_repr}
• Value must be one of {pp_values}
• Value must be a nonnegative integer or None
• Value must be a callable

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/33d3de5e4b13b346. Report an issue: GitHub.