headroomlabs-ai/headroom · warning · AttributeError

unknown ProxyConfig field: {key}

Error message

unknown ProxyConfig field: {key}

What it means

AttributeError raised by Headroom.configure_proxy (headroom/testing/harness.py:727) when the overrides kwargs contain a name that the ProxyConfig object does not have (hasattr check fails). Unlike the generic __setattr__ path (378), this builder validates each override explicitly and names the offending key, so typos and version-drifted field names fail fast with a precise message. configure_headroom has the mirror-image check for HeadroomConfig.

Source

Thrown at headroom/testing/harness.py:727

    OnPlatform = on_platform

    def configure(self, callback: ConfigCallback | None = None, **overrides: Any) -> Headroom:
        configurator = Configurator(self._headroom_config, self._proxy_config)
        if callback is not None:
            callback(configurator)
        for key, value in overrides.items():
            setattr(configurator, key, value)
        return self

    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,

View on GitHub (pinned to 322425c43b)

Solutions

1. Check dir(proxy_config) or the ProxyConfig definition for the exact field name.
2. Fix the typo / use the current field name.
3. Verify you are on the headroom version whose docs you are reading.
4. If you don't need per-key checking, note configure() applies overrides unchecked — but prefer fixing the name.

Example fix

# before
harness.configure_proxy(mode='cache', timout=30)  # AttributeError: unknown ProxyConfig field: timout

# after
harness.configure_proxy(mode='cache', timeout=30)

overrides = {'mode': 'cache', 'timout': 30}
unknown = [k for k in overrides if not hasattr(proxy_config, k)]
if unknown:
    raise TypeError(f'unknown ProxyConfig fields: {unknown}')
harness.configure_proxy(**overrides)

def known_proxy_fields(config, overrides: dict) -> list[str]:
    return [k for k in overrides if hasattr(config, k)]

When it happens

Trigger: Headroom...configure_proxy(mode='cache', retrys=3) — 'retrys' not a ProxyConfig field; using a field from release notes of a newer headroom than installed; mixing HeadroomConfig field names into configure_proxy.

Common situations: Chaining fluent builders from README examples against an older installed version; field renamed between majors; copy-pasting configure(...) kwargs (which are NOT checked) into configure_proxy(...) (which are).

Related errors

• unknown Headroom harness config field: {name}
• mode must be 'token' or 'cache'
• {name} is read-only; mutate its fields instead
• duplicate scenario name in suite: {built.name}
• HeadroomSuite requires at least one scenario

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