aio-libs/aiohttp · error · TypeError

Inheritance class from ChainMapProxy is forbidden

Error message

Inheritance class {cls.__name__} from ChainMapProxy is forbidden

What it means

ChainMapProxy.__init_subclass__ raises TypeError when any class attempts to inherit from ChainMapProxy. The class is decorated with @final and uses __init_subclass__ as a hard guard to prevent subclassing. ChainMapProxy is an internal read-only mapping view used for Application storage; subclassing could break its invariants.

Solutions

1. Do not subclass ChainMapProxy — use composition instead (wrap it in your own class)
2. If you need custom storage behavior, subclass aiohttp.web.Application or use a separate storage object
3. Access ChainMapProxy only through the documented Application API: app['key'] or app.get(key)

Example fix

# before
from aiohttp.helpers import ChainMapProxy
class MyProxy(ChainMapProxy):  # TypeError at class definition
    pass

# after (composition, not inheritance)
class MyStorageWrapper:
    def __init__(self, proxy: ChainMapProxy):
        self._proxy = proxy
    def get_with_default(self, key, default=None):
        return self._proxy.get(key, default)

# No validation needed at runtime — this is a design-time error.
# Ensure your codebase does not import or subclass ChainMapProxy.
# Use Application's public API instead.
from aiohttp.web import Application
app = Application()
app['my_key'] = 'value'  # correct way to store data

When it happens

Trigger: Attempting to create a subclass: class MyProxy(ChainMapProxy): ... — the __init_subclass__ classmethod fires at class definition time, before __init__, and immediately raises TypeError.

Common situations: Trying to extend ChainMapProxy to add custom behavior to the aiohttp Application storage; copy-pasting from code that extends Mapping without realizing ChainMapProxy is @final; attempting to add type annotations or mixins to the storage layer.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• KeyError
• Can not serialize value type: %r headers: %r value: %r
• Changing state of started or joined application is forbidden
• content_type must be an instance of str. Got
• data argument must be byte-ish (%r)

AI-assisted analysis of aio-libs/aiohttp@d041d4d0fd (2026-08-11). Data as JSON: /api/errors/5a2b944f29df3ecf. Report an issue: GitHub.

Appendix: source

Thrown at aiohttp/helpers.py:967

class RequestKey(BaseKey[_T]):
    """Keys for static typing support in Request."""


class ResponseKey(BaseKey[_T]):
    """Keys for static typing support in Response."""


@final
class ChainMapProxy(Mapping[str | AppKey[Any], Any]):
    __slots__ = ("_maps",)

    def __init__(self, maps: Iterable[Mapping[str | AppKey[Any], Any]]) -> None:
        self._maps = tuple(maps)

    def __init_subclass__(cls) -> None:
        raise TypeError(
            f"Inheritance class {cls.__name__} from ChainMapProxy is forbidden"
        )

    @overload  # type: ignore[override]
    def __getitem__(self, key: AppKey[_T]) -> _T: ...

    @overload
    def __getitem__(self, key: str) -> Any: ...

    def __getitem__(self, key: str | AppKey[_T]) -> Any:
        for mapping in self._maps:
            try:
                return mapping[key]
            except KeyError:
                pass
        raise KeyError(key)

    @overload  # type: ignore[override]

View on GitHub (pinned to d041d4d0fd)