pola-rs/polars · error · AttributeError

cannot override reserved namespace {name!r}

Error message

cannot override reserved namespace {name!r}

What it means

AttributeError from _create_namespace's inner decorator (py-polars/src/polars/api.py:53-56). register_expr/dataframe/lazyframe/series_namespace validate the chosen name against _reserved_namespaces, which is the union of _accessors already registered on polars' own classes ('str', 'dt', 'cat', 'list', 'name', 'meta', 'string', 'temporal', 'cat', 'list', 'struct', ...). Decorating with one of these names tries to shadow a built-in polars namespace and is hard-rejected.

Source

Thrown at py-polars/src/polars/api.py:56

    def __get__(self, instance: NS | None, cls: type[NS]) -> NS | type[NS]:
        if instance is None:
            return self._ns

        ns_instance = self._ns(instance)  # type: ignore[call-arg]
        setattr(instance, self._accessor, ns_instance)
        return ns_instance


def _create_namespace(
    name: str, cls: type[Expr | DataFrame | LazyFrame | Series]
) -> Callable[[type[NS]], type[NS]]:
    """Register custom namespace against the underlying Polars class."""

    def namespace(ns_class: type[NS]) -> type[NS]:
        if name in _reserved_namespaces:
            msg = f"cannot override reserved namespace {name!r}"
            raise AttributeError(msg)
        elif (attr := getattr(cls, name, None)) is not None:
            if isfunction(attr) or isinstance(attr, property) or name.startswith("_"):
                msg = f"cannot override `{cls.__name__}.{name}` with custom namespace {ns_class.__name__!r}"
                raise AttributeError(msg)
            warn(
                f"overriding existing custom namespace {name!r} (on {cls.__name__})",
                UserWarning,
                stacklevel=find_stacklevel(),
            )

        setattr(cls, name, NameSpace(name, ns_class))
        cls._accessors.add(name)
        return ns_class

    return namespace


def register_expr_namespace(name: str) -> Callable[[type[NS]], type[NS]]:

View on GitHub (pinned to df599052da)

Solutions

1. Pick a distinct namespace name, e.g. 'geo', 'text', 'mylib'
2. Prefix extension namespaces with a short project prefix to avoid collisions
3. If migrating old code, update all call sites from df.<old>() to df.<new>()

Example fix

# before
@pl.register_series_namespace('str')
class StrExt: ...

# after
@pl.register_series_namespace('text')
class StrExt: ...

import polars as pl

def namespace_name_ok(name: str, cls) -> bool:
    return not hasattr(cls, name)

When it happens

Trigger: @pl.register_series_namespace('str'), @pl.register_dataframe_namespace('dt'), or any decorator name that equals an existing polars accessor found in cls._accessors.

Common situations: Writing a generic plugin library that picks namespace names like 'str' or 'dt' because they feel natural; name collisions between an extension package and polars' own namespaces added in newer releases.

Related errors

• cannot override `{cls.__name__}.{name}` with custom namespac
• '{type(self).__name__}' object has no attribute {name!r}. Di
• '{type(self).__name__}' object has no attribute {name!r}
• Altair has no method 'mark_{attr}'
• cannot select columns using key of type {qualified_type_name

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/4814e66354e3e9a1. Report an issue: GitHub.