zylon-ai/private-gpt · error · ValueError

Local storage provider requires local_root_path

Error message

Local storage provider requires local_root_path

What it means

Raised by StorageComponent when creating storage with provider="local" but local_root_path=None. The factory method requires a root path to construct a LocalObjectStorage; both parameters default to None so the caller must supply the one matching the chosen provider. It is a configuration/validation error thrown before any filesystem access happens.

Source

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

        self._lock = threading.RLock()
        self._storages: dict[str, ObjectStorage] = {}

    def get_object_storage(
        self,
        provider: str,
        local_root_path: str | None = None,
        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. Set the local root path in configuration (e.g. storage: local_root_path: /var/lib/private_gpt/local_storage) so the factory receives a non-None value
2. If calling the factory directly, pass local_root_path="/some/path" as the second argument
3. Add a pydantic validator on Settings to fail fast at startup with a clearer message when provider is local and the path is missing

Example fix

# before
storage = storage_component.get_storage(provider="local")
# after
storage = storage_component.get_storage(
    provider="local",
    local_root_path=settings.storage.local_root_path,
)

from private_gpt.components.storage.storage_component import StorageComponent

def validate_local_storage(sc: StorageComponent, local_root_path: str | None) -> None:
    if local_root_path is None:
        raise ValueError("configure storage.local_root_path before provider=local")
    sc.get_storage(provider="local", local_root_path=local_root_path)

def is_local_storage_ready(provider: str, local_root_path: str | None) -> bool:
    return provider != "local" or local_root_path is not None

When it happens

Trigger: Calling the storage factory method with provider="local" and omitting local_root_path (it defaults to None). Typically happens when settings (e.g. storage.local_root_path) are missing from the YAML/env config and None is passed through.

Common situations: Fresh deployment with an incomplete settings.yaml; renaming of the settings key between versions; tests that construct the component without a full Settings object.

Related errors

• S3 storage provider requires bucket_name
• Unsupported storage provider: {provider}
• TOOL_NAME_CONFLICT
• INVALID_REQUEST_ERROR
• 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/1c3d10a60afd2138. Report an issue: GitHub.