zylon-ai/private-gpt · error · ValueError

S3 storage provider requires bucket_name

Error message

S3 storage provider requires bucket_name

What it means

Raised by StorageComponent when provider="s3" is selected but bucket_name is None. The S3ObjectStorage constructor needs a concrete bucket to operate on, so the factory refuses to build an instance without one. This is a pure configuration error raised before any AWS call is made.

Source

Thrown at private_gpt/components/storage/storage_component.py:46

        bucket_name: str | None = None,
    ) -> ObjectStorage:
        key = f"{provider}:{local_root_path}:{bucket_name}"
        with self._lock:
            storage = self._storages.get(key)
            if storage is not None:
                return storage

            match provider:
                case "local":
                    if local_root_path is None:
                        raise ValueError(
                            "Local storage provider requires local_root_path"
                        )

                    storage = LocalObjectStorage(root_path=local_root_path)
                case "s3":
                    if bucket_name is None:
                        raise ValueError("S3 storage provider requires bucket_name")
                    storage = S3ObjectStorage(
                        s3_helper=self._injector.get(S3Helper),
                        bucket_name=bucket_name,
                    )
                case _:
                    raise ValueError(f"Unsupported storage provider: {provider}")

            self._storages[key] = storage
            return storage

View on GitHub (pinned to 4a030776a3)

Solutions

1. Add the bucket name to configuration (e.g. storage: bucket_name: my-ingestion-bucket)
2. If calling the factory directly, pass bucket_name explicitly
3. Verify the settings key spelling matches what the component reads, and add a startup check that provider-specific fields are set

Example fix

# before
storage = storage_component.get_storage(provider="s3")
# after
storage = storage_component.get_storage(
    provider="s3",
    bucket_name=settings.storage.bucket_name,
)

def validate_s3_storage(sc, bucket_name: str | None) -> None:
    if bucket_name is None:
        raise ValueError("configure storage.bucket_name before provider=s3")
    sc.get_storage(provider="s3", bucket_name=bucket_name)

def is_s3_storage_ready(provider: str, bucket_name: str | None) -> bool:
    return provider != "s3" or bucket_name is not None

When it happens

Trigger: Calling the storage factory with provider="s3" and omitting bucket_name. Common when the S3 bucket setting is absent from settings.yaml or the environment while the provider is set to s3.

Common situations: Migrating from local to S3 storage without adding the bucket setting; per-environment configs where the bucket name is only defined in prod; typos in the settings key name.

Related errors

• INVALID_REQUEST_ERROR
• Local storage provider requires local_root_path
• Unsupported storage provider: {provider}
• TOOL_NAME_CONFLICT
• LLM mode '{mode}' is not supported. Available: {available}

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/bb029a2591a14ca5. Report an issue: GitHub.