agentscope-ai/agentscope · error · ImportError

S3BlobStore requires the optional dependency ``aioboto3``. I

Error message

S3BlobStore requires the optional dependency ``aioboto3``. Install it with ``uv pip install aioboto3`` or with the ``[s3]`` extra.

What it means

S3BlobStore.__init__ lazily imports aioboto3 and raises ImportError if it is absent, because the S3 backend is an optional feature gated behind the [s3] extra. The error message tells you exactly how to install it. Raising at construction (rather than first use) fails fast so misconfiguration surfaces immediately.

Source

Thrown at src/agentscope/app/rag/blob_store/_s3.py:111

            aws_secret_access_key (`str | None`, optional):
                Paired with ``aws_access_key_id``.
            session_token (`str | None`, optional):
                For STS-issued temporary credentials.
            use_ssl (`bool`, defaults to ``True``):
                Force HTTPS. Production deployments must keep this on;
                local MinIO with self-signed certs is the only place
                ``False`` is reasonable.
            config (`Any | None`, optional):
                ``aiobotocore.config.AioConfig`` instance for users who
                need to tune timeouts, retry mode, signature version
                (e.g. ``s3v4`` for Aliyun OSS), or addressing style.
                Path-style addressing is needed for MinIO; pass
                ``AioConfig(s3={"addressing_style": "path"})``.
        """
        try:
            import aioboto3
        except ImportError as e:
            raise ImportError(
                "S3BlobStore requires the optional dependency ``aioboto3``. "
                "Install it with ``uv pip install aioboto3`` or with the "
                "``[s3]`` extra.",
            ) from e

        self._bucket = bucket
        self._region_name = region_name
        self._endpoint_url = endpoint_url
        self._aws_access_key_id = aws_access_key_id
        self._aws_secret_access_key = aws_secret_access_key
        self._session_token = session_token
        self._use_ssl = use_ssl
        self._config = config

        # Session is cheap; the actual transport is the ``client``
        # context manager opened per call. We deliberately do NOT
        # cache a long-lived client across the lifespan: aiobotocore
        # clients hold an aiohttp connection pool tied to a loop, and

View on GitHub (pinned to e90f1c7592)

Solutions

1. Install it: pip install aioboto3 (or reinstall agentscope with the [s3] extra)
2. Add aioboto3 to your deployment requirements/lockfile
3. Confirm you're in the right environment: python -c 'import aioboto3' with the same interpreter
4. In multi-backend code, catch ImportError and fall back to LocalBlobStore when S3 is not configured

Example fix

# before
store = S3BlobStore(bucket='my-bucket')  # ImportError

# after
# shell:
pip install aioboto3
store = S3BlobStore(bucket='my-bucket')

def s3_support() -> bool:
    try:
        import aioboto3  # noqa: F401
        return True
    except ImportError:
        return False

if s3_support():
    store = S3BlobStore(bucket=b)
else:
    raise SystemExit('Install aioboto3 for S3 blob storage')

null

try:
    store = S3BlobStore(bucket=b)
except ImportError:
    # optional-dependency guard: install aioboto3 or fall back
    raise

When it happens

Trigger: Instantiating S3BlobStore(bucket=...) in an environment where 'import aioboto3' fails — package not installed, or installed in a different interpreter/venv than the running process.

Common situations: Deploying to a slim Docker image or CI runner without the s3 extra; multiple virtualenvs where aioboto3 was installed in the wrong one; dependency-resolution tools dropping aioboto3 because nothing statically imports it.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• The 'redis' package is required for RedisMessageBus. Install
• S3BlobStore is not entered; use it inside ``async with`` bef
• Not an S3 blob URI: {uri!r}
• Malformed S3 blob URI: {uri!r}
• Bucket {bucket!r} in URI {uri!r} does not match configured b

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