pandas-dev/pandas · error · ValueError

Cannot override builtin dialect.

Error message

Cannot override builtin dialect.

What it means

Raised by the `with_csv_dialect` context manager (in pandas._testing.contexts) when the requested dialect name collides with one of Python's csv builtin dialects: `excel`, `excel-tab`, or `unix`. The guard prevents tests from clobbering globally registered builtin dialects, which would leak across the test suite and corrupt other tests' CSV parsing.

Solutions

1. Choose a non-builtin dialect name (e.g. 'excel-semicolon', 'test-custom').
2. If you must vary a builtin's behavior, register under a unique name and reference that.
3. Add a guard in test parametrization to skip builtin names.

Example fix

// before
with with_csv_dialect('excel', delimiter=';'):
    ...

// after
with with_csv_dialect('excel-semicolon', delimiter=';'):
    ...

_BUILTIN = {'excel', 'excel-tab', 'unix'}
assert name not in _BUILTIN, f'{name} is a builtin csv dialect'

When it happens

Trigger: Calling `with with_csv_dialect('excel', delimiter=';'):` in a test; parameterizing a test over dialect names that include one of the three builtins.

Common situations: Writing a test that wants to define a custom CSV dialect and accidentally reusing a builtin name; copy-paste of dialect names between test files.

Related errors

• check_like must be False if check_index is False
• Expected type , found instead
• [datetimelike_compat=True]
• {err_msg}
• is not

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

Appendix: 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 3b7651241d)