What causes "No optimizer registered for '{key}'. Available: {available}" in headroomlabs-ai/headroom?

Import the module that registers the optimizer before calling get (e.g. from headroom.cache import anthropic_optimizer) so its @OptimizerRegistry.register decorator runs

headroomlabs-ai/headroom · error · KeyError

No optimizer registered for '{key}'. Available: {available}

Error message

No optimizer registered for '{key}'. Available: {available}

What it means

The optimizer registry (headroom/cache/registry.py) maps provider or provider-tier keys to optimizer classes. get_optimizer builds a key f"{provider}-{tier}" for non-oss tiers and falls back to the bare provider name if that enterprise key is absent; if neither is registered it raises KeyError listing the available keys. The error therefore means neither the tier-specific nor the base provider optimizer was registered — typically because the provider module that registers it was never imported.

Source

Thrown at headroom/cache/registry.py:109

        Returns:
            Cache optimizer instance

        Raises:
            KeyError: If no optimizer registered for provider/tier
        """
        # Build the lookup key
        if tier != "oss":
            key = f"{provider}-{tier}"
            # Fall back to OSS if enterprise not available
            if key not in cls._optimizers:
                key = provider
        else:
            key = provider

        if key not in cls._optimizers:
            available = list(cls._optimizers.keys())
            raise KeyError(f"No optimizer registered for '{key}'. Available: {available}")

        # Return cached instance if requested
        cache_key = f"{key}:{id(config)}" if config else key
        if cached and cache_key in cls._instances:
            return cls._instances[cache_key]

        # Create new instance
        optimizer_class = cls._optimizers[key]
        instance = optimizer_class(config)

        if cached:
            cls._instances[cache_key] = instance

        return instance

    @classmethod
    def list_providers(cls) -> list[str]:
        """List all registered provider names (excluding tier suffixes)."""

View on GitHub (pinned to 322425c43b)

Solutions

Import the module that registers the optimizer before calling get (e.g. from headroom.cache import anthropic_optimizer) so its @OptimizerRegistry.register decorator runs
Use a key from the 'Available: [...]' list in the message — match provider name and drop to tier='oss' if the enterprise variant isn't registered
Verify spelling and case of provider ('anthropic', 'openai', 'google') against the registered keys
If you implemented a custom optimizer, register it explicitly with OptimizerRegistry.register(key, cls)

Example fix

# before
opt = OptimizerRegistry.get(provider="anthropic", tier="enterprise")  # KeyError

# after
from headroom.cache.anthropic_optimizer import register as _reg  # side-effect registers key
_reg()
opt = OptimizerRegistry.get(provider="anthropic", tier="oss")

Defensive patterns

Strategy: validation

Validate before calling

from headroom.cache.registry import OptimizerRegistry
key = f"{provider}-{tier}" if tier != "oss" else provider
if key not in OptimizerRegistry._optimizers and provider not in OptimizerRegistry._optimizers:
    raise SystemExit(f"optimizer {key!r} not registered; import its module first")

Type guard

def optimizer_available(provider: str, tier: str = "oss") -> bool:
    from headroom.cache.registry import OptimizerRegistry
    opts = OptimizerRegistry._optimizers
    return (f"{provider}-{tier}" if tier != "oss" else provider) in opts or provider in opts

Try / catch

try:
    opt = OptimizerRegistry.get(provider=provider, tier=tier, config=cfg)
except KeyError as e:
    opt = OptimizerRegistry.get(provider=provider, tier="oss", config=cfg)  # downgrade tier

Prevention

Import all provider optimizer modules once at app startup so registrations are side-effected
Normalize provider strings to lowercase at config load time
Unit-test that every provider you configure resolves before deploying

When it happens

Trigger: Calling OptimizerRegistry.get(...) (or the cache API that delegates to it) with provider='anthropic', tier='enterprise' when only 'anthropic' or only OSS optimizers are registered; or any provider whose registering module (e.g. the anthropic/openai optimizer module) has not been imported yet, since registration happens at import time.

Common situations: Passing an enterprise tier without the enterprise extra installed; refactors that removed an import side effect; typo'd provider names ('Anthropic' vs 'anthropic'); running a minimal install where only some provider optimizers are available.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/e2553ed98652efc7. Report an issue: GitHub.