agentscope-ai/agentscope · error · AttributeError

module 'agentscope.app.storage' has no attribute {name!r}

Error message

module 'agentscope.app.storage' has no attribute {name!r}

What it means

The agentscope.app.storage package exposes StorageBase and lazy-loads some backends via module-level __getattr__. Requesting any attribute other than the explicitly supported names (e.g. AsyncSQLAlchemyStorage) raises AttributeError, because the package does not eagerly import all storage classes.

Source

Thrown at src/agentscope/app/storage/__init__.py:63

    # ``_sql`` package does at load time (its declarative-tables module
    # cannot defer it).
    from ._sql import AsyncSQLAlchemyStorage  # noqa: F401


def __getattr__(name: str) -> object:
    """Lazily load the optional SQL backend on first attribute access.

    Keeps ``import agentscope.app.storage`` cheap — ``StorageBase``,
    ``RedisStorage`` and the record models never need SQLAlchemy — while
    still exposing ``AsyncSQLAlchemyStorage`` from this package for
    callers that do ``from agentscope.app.storage import
    AsyncSQLAlchemyStorage``. SQLAlchemy is imported only at that point.
    """
    if name == "AsyncSQLAlchemyStorage":
        from ._sql import AsyncSQLAlchemyStorage as _AsyncSQLAlchemyStorage

        return _AsyncSQLAlchemyStorage
    raise AttributeError(
        f"module 'agentscope.app.storage' has no attribute {name!r}",
    )


__all__ = [
    "StorageBase",
    "RedisStorage",
    "AsyncSQLAlchemyStorage",
    # The ORM models
    "InviteConfig",
    "AgentData",
    "AgentRecord",
    "ChannelBinding",
    "ChannelRecord",
    "ChunkerConfig",
    "RoutingConfig",
    "SessionScope",
    "SessionSettings",

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check agentscope.app.storage.__all__ / dir() to see which names the package actually exports
2. Use the supported name: from agentscope.app.storage import AsyncSQLAlchemyStorage
3. Import from the concrete submodule if you need an internal class: from agentscope.app.storage._sql import AsyncSQLAlchemyStorage
4. Verify class name spelling and that your agentscope version includes that backend

Example fix

// before
from agentscope.app.storage import SQLAlchemyStorage  # AttributeError

// after
from agentscope.app.storage import AsyncSQLAlchemyStorage

import agentscope.app.storage as storage_pkg

name = "AsyncSQLAlchemyStorage"
if not hasattr(storage_pkg, name):
    raise SystemExit(f"backend {name} unavailable; see {storage_pkg.__all__}")

from agentscope.app.storage import StorageBase

def is_storage_backend(obj) -> TypeGuard[type[StorageBase]]:
    return isinstance(obj, type) and issubclass(obj, StorageBase)

When it happens

Trigger: Calling agentscope.app.storage.SomeBackend where SomeBackend is not StorageBase or AsyncSQLAlchemyStorage, e.g. `from agentscope.app.storage import MongoDBStorage` or `agentscope.app.storage.SQLAlchemyStorage` (the sync name).

Common situations: Guessing backend class names that don't exist, using the sync 'SQLAlchemyStorage' name instead of 'AsyncSQLAlchemyStorage', or referencing a backend that lives in a submodule (agentscope.app.storage._sql) directly after a version refactor moved classes behind lazy imports.

Related errors

• module {__name__!r} has no attribute {name!r}
• {key}
• This storage backend has no channel support.
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• factory must be a callable, got {type(factory).__name__}

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