headroomlabs-ai/headroom · error · AttributeError

unknown HeadroomConfig field: {key}

Error message

unknown HeadroomConfig field: {key}

What it means

Raised by Headroom.configure_headroom() when an override keyword does not match any attribute on the HeadroomConfig object. The method first applies an optional callback, then setattr's each **overrides key onto self._headroom_config after verifying it with hasattr; an unknown key aborts the fluent chain. It exists to catch typos in configuration names early instead of silently creating new attributes.

Source

Thrown at headroom/testing/harness.py:738

    Configure = configure

    def configure_proxy(self, callback: ProxyCallback | None = None, **overrides: Any) -> Headroom:
        if callback is not None:
            callback(self._proxy_config)
        for key, value in overrides.items():
            if not hasattr(self._proxy_config, key):
                raise AttributeError(f"unknown ProxyConfig field: {key}")
            setattr(self._proxy_config, key, value)
        return self

    ConfigureProxy = configure_proxy

    def configure_headroom(self, callback: SdkCallback | None = None, **overrides: Any) -> Headroom:
        if callback is not None:
            callback(self._headroom_config)
        for key, value in overrides.items():
            if not hasattr(self._headroom_config, key):
                raise AttributeError(f"unknown HeadroomConfig field: {key}")
            setattr(self._headroom_config, key, value)
        return self

    ConfigureHeadroom = configure_headroom

    def with_compression(
        self,
        *,
        mode: Literal["token", "cache"] | None = None,
        kompress: bool | None = None,
        force_kompress_all: bool | None = None,
        lossless: bool | None = None,
        compressors: set[str] | Sequence[str] | Literal["*"] | None = None,
        min_tokens: int | None = None,
        max_items: int | None = None,
        savings_profile: str | None = None,
    ) -> Headroom:
        """Configure proxy and SDK compression posture with real config fields."""

View on GitHub (pinned to 322425c43b)

Solutions

1. Inspect the actual field names: `from headroom import Headroom; print([a for a in dir(Headroom()._headroom_config) if not a.startswith('_')])` (or read the HeadroomConfig dataclass) and correct the keyword.
2. If the option controls the proxy (mode, optimize, port, ...), move it to configure_proxy(...)/ConfigureProxy(...).
3. If upgrading headroom, diff the changelog for renamed HeadroomConfig fields and update the call.
4. Guard programmatically: build the overrides dict and filter with hasattr(config, key) before calling.

Example fix

# before
headroom.configure_headroom(context_window=200_000, mode="token")

# after
headroom.configure_headroom(context_window=200_000)
headroom.configure_proxy(mode="token")

from dataclasses import fields
valid = {f.name for f in fields(type(harness._headroom_config))}
overrides = {k: v for k, v in overrides.items() if k in valid}
missing = set(overrides) - set(valid)

def is_valid_headroom_override(key: str) -> bool:
    return hasattr(harness._headroom_config, key)

try:
    headroom.configure_headroom(**overrides)
except AttributeError as e:
    if "unknown HeadroomConfig field" in str(e):
        key = str(e).rsplit(":", 1)[1].strip()
        raise ConfigError(f"bad headroom override {key!r}; valid: {headroom_config_fields()}") from e
    raise

When it happens

Trigger: Calling headroom.configure_headroom(max_context_windw=200000) (typo), or passing an option that belongs to ProxyConfig (e.g. configure_headroom(mode='token')) instead of configure_proxy, or using a field name removed/renamed in a newer Headroom version.

Common situations: Copy-pasting config snippets from older docs or examples where fields were renamed; mixing up headroom vs proxy options in a builder chain; IDE autocompleting a similarly-named attribute.

Related errors

• invalid upstream URL: {0}
• compression engine startup failed: {0}
• failed to read simulator config {path}: {source}
• simulator config is not valid JSON: {0}
• Unknown provider: {self.provider}

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