{"record":{"id":"3522b922b14881ce","repo":"agentscope-ai/agentscope","slug":"s3blobstore-requires-the-optional-dependency-aio","errorCode":null,"errorMessage":"S3BlobStore requires the optional dependency ``aioboto3``. Install it with ``uv pip install aioboto3`` or with the ``[s3]`` extra.","messagePattern":"S3BlobStore requires the optional dependency ``aioboto3``\\. Install it with ``uv pip install aioboto3`` or with the ``\\[s3\\]`` extra\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/agentscope/app/rag/blob_store/_s3.py","lineNumber":111,"sourceCode":"            aws_secret_access_key (`str | None`, optional):\n                Paired with ``aws_access_key_id``.\n            session_token (`str | None`, optional):\n                For STS-issued temporary credentials.\n            use_ssl (`bool`, defaults to ``True``):\n                Force HTTPS. Production deployments must keep this on;\n                local MinIO with self-signed certs is the only place\n                ``False`` is reasonable.\n            config (`Any | None`, optional):\n                ``aiobotocore.config.AioConfig`` instance for users who\n                need to tune timeouts, retry mode, signature version\n                (e.g. ``s3v4`` for Aliyun OSS), or addressing style.\n                Path-style addressing is needed for MinIO; pass\n                ``AioConfig(s3={\"addressing_style\": \"path\"})``.\n        \"\"\"\n        try:\n            import aioboto3\n        except ImportError as e:\n            raise ImportError(\n                \"S3BlobStore requires the optional dependency ``aioboto3``. \"\n                \"Install it with ``uv pip install aioboto3`` or with the \"\n                \"``[s3]`` extra.\",\n            ) from e\n\n        self._bucket = bucket\n        self._region_name = region_name\n        self._endpoint_url = endpoint_url\n        self._aws_access_key_id = aws_access_key_id\n        self._aws_secret_access_key = aws_secret_access_key\n        self._session_token = session_token\n        self._use_ssl = use_ssl\n        self._config = config\n\n        # Session is cheap; the actual transport is the ``client``\n        # context manager opened per call. We deliberately do NOT\n        # cache a long-lived client across the lifespan: aiobotocore\n        # clients hold an aiohttp connection pool tied to a loop, and","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/app/rag/blob_store/_s3.py#L93-L129","documentation":"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.","triggerScenarios":"Instantiating S3BlobStore(bucket=...) in an environment where 'import aioboto3' fails — package not installed, or installed in a different interpreter/venv than the running process.","commonSituations":"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.","solutions":["Install it: pip install aioboto3 (or reinstall agentscope with the [s3] extra)","Add aioboto3 to your deployment requirements/lockfile","Confirm you're in the right environment: python -c 'import aioboto3' with the same interpreter","In multi-backend code, catch ImportError and fall back to LocalBlobStore when S3 is not configured"],"exampleFix":"# before\nstore = S3BlobStore(bucket='my-bucket')  # ImportError\n\n# after\n# shell:\npip install aioboto3\nstore = S3BlobStore(bucket='my-bucket')","handlingStrategy":"validation","validationCode":"def s3_support() -> bool:\n    try:\n        import aioboto3  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif s3_support():\n    store = S3BlobStore(bucket=b)\nelse:\n    raise SystemExit('Install aioboto3 for S3 blob storage')","typeGuard":"null","tryCatchPattern":"try:\n    store = S3BlobStore(bucket=b)\nexcept ImportError:\n    # optional-dependency guard: install aioboto3 or fall back\n    raise","preventionTips":["Include aioboto3 in prod images and lockfiles when using S3BlobStore","Add 'import aioboto3' to a startup dependency check","Gate S3 usage behind a config flag validated at boot"],"tags":["s3","blob-store","missing-dependency","importerror"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}