zylon-ai/private-gpt · error · ValueError

Sandbox provider '{name}' is not registered. Available: {ava

Error message

Sandbox provider '{name}' is not registered. Available: {available}

What it means

The sandbox registry lazily instantiates providers from the _PROVIDERS class-level factory map; get_provider raises ValueError naming the requested provider and the sorted list of available ones when the name is unknown. Both a miss in the per-instance cache and in _PROVIDERS triggers it, so the name was never a compiled-in provider — this is a configuration/naming error, not a runtime state issue.

Source

Thrown at private_gpt/components/sandbox/registry.py:28

def register_sandbox(name: str, provider: SandboxProviderFactory) -> None:
    _PROVIDERS[name] = provider


class SandboxProviderRegistry:
    def __init__(self, settings: Settings) -> None:
        self._settings = settings
        self._providers: dict[str, SandboxProvider] = {}

    def get_provider(self, name: str) -> SandboxProvider:
        provider = self._providers.get(name)
        if provider is not None:
            return provider

        provider_factory = _PROVIDERS.get(name)
        if provider_factory is None:
            available = ", ".join(sorted(_PROVIDERS)) or "none"
            raise ValueError(
                f"Sandbox provider '{name}' is not registered. Available: {available}"
            )
        provider = provider_factory(self._settings)
        self._providers[name] = provider
        return provider

View on GitHub (pinned to 4a030776a3)

Solutions

Use one of the names listed in the error's 'Available: ...' section.
Fix the settings value that supplies the name (e.g. settings.sandbox.provider) — strip whitespace and correct casing.
If the provider should exist, verify the private-gpt build actually includes it (some providers may be optional/flagged at build time) and update the package.
Fail fast at startup: validate the configured provider name against the registry before serving requests.

Example fix

# before
provider = registry.get_provider("kubernetes")  # ValueError: not registered

# after
provider = registry.get_provider("local")  # name from the 'Available:' list

Defensive patterns

Strategy: validation

Validate before calling

from private_gpt.components.sandbox.registry import SandboxRegistry

PROVIDERS = {"local"}  # names valid for this build

def validate_provider(name: str) -> str:
    if name not in PROVIDERS:
        raise ValueError(f"provider must be one of {sorted(PROVIDERS)}, got {name!r}")
    return name

Type guard

def is_registered_provider(registry: SandboxRegistry, name: str) -> bool:
    try:
        registry.get_provider(name)
        return True
    except ValueError:
        return False

Try / catch

try:
    provider = registry.get_provider(settings.sandbox.provider)
except ValueError as e:
    raise SystemExit(f"Bad sandbox config: {e}") from e

Prevention

Validate the provider name against the registry at application startup, not per request.
Strip/normalize whitespace and case from config-supplied provider names.
Pin config values to the provider set of the exact private-gpt version you deploy.

When it happens

Trigger: Calling registry.get_provider(name) with a name that is not a key in _PROVIDERS — e.g. settings.sandbox.provider set to 'k8s' when only 'local'/'docker' style keys exist, or a typo like 'locaL'.

Common situations: Config copied from another deployment whose provider set differs; provider removed/renamed across private-gpt versions; environment-specific settings (dev uses local, prod expects a provider not built into this image); case/whitespace typos in YAML config.

Related errors

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