headroomlabs-ai/headroom · warning · AttributeError

unknown Headroom harness config field: {name}

Error message

unknown Headroom harness config field: {name}

What it means

AttributeError raised by HeadroomConfig's __setattr__ (headroom/testing/harness.py:575) when an attribute is assigned that is not recognized anywhere: not a property setter on the config class, not an attribute of the nested proxy config, and not an attribute of the nested headroom config. The setter deliberately forwards unknown-but-valid names to the nested configs, so reaching this error means the name is a typo or a field that does not exist in either sub-config (e.g. a field removed in a newer headroom version).

Source

Thrown at headroom/testing/harness.py:575

    @default_mode.setter
    def default_mode(self, value: str | HeadroomMode) -> None:
        self.headroom.default_mode = _coerce_headroom_mode(value)

    def __setattr__(self, name: str, value: Any) -> None:
        if name in {"headroom", "proxy"}:
            raise AttributeError(f"{name} is read-only; mutate its fields instead")
        descriptor = getattr(type(self), name, None)
        if isinstance(descriptor, property) and descriptor.fset is not None:
            descriptor.fset(self, value)
            return
        if hasattr(self.proxy, name):
            setattr(self.proxy, name, value)
            return
        if hasattr(self.headroom, name):
            setattr(self.headroom, name, value)
            return
        raise AttributeError(f"unknown Headroom harness config field: {name}")


class Headroom:
    """Fluent scenario builder.

    Example:
        ``Headroom.with_bedrock(region="us-east-1").on_apple_silicon().configure(...)``
    """

    HARNESS_VERSION = "1"

    def __init__(
        self,
        *,
        name: str = "headroom-scenario",
        provider: ProviderTarget = ProviderTarget.ANTHROPIC,
        platform: PlatformTarget = PlatformTarget.LOCAL,
        headroom_config: HeadroomConfig | None = None,

View on GitHub (pinned to 322425c43b)

Solutions

1. Check the spelling against ProxyConfig/HeadroomConfig attributes (dir(harness.config.proxy)).
2. Prefer the type-checked builders configure_proxy(mode=...) / configure_headroom(...) which give a clearer per-field error (379).
3. Upgrade/align headroom to the version whose fields you are coding against.

Example fix

# before
harness.config.proxy_mod = 'cache'  # AttributeError: unknown field

# after
harness.configure_proxy(mode='cache')

def can_set(harness, name: str) -> bool:
    cfg = harness.config
    return (
        getattr(type(cfg), name, None) is not None
        or hasattr(cfg.proxy, name)
        or hasattr(cfg.headroom, name)
    )

def is_known_harness_field(harness, name: str) -> bool:
    cfg = harness.config
    d = getattr(type(cfg), name, None)
    return d is not None or hasattr(cfg.proxy, name) or hasattr(cfg.headroom, name)

try:
    harness.config.optmize = True
except AttributeError as e:
    raise RuntimeError(f'check field name: {e}') from e

When it happens

Trigger: harness.config.proxy_mod = 'cache' (typo); harness.config.some_new_field = 1 after reading docs for a version newer/older than the installed one; assigning a field that only exists on HeadroomConfig's sibling types.

Common situations: Version drift between docs and installed package; autocomplete suggesting stale field names; test code written against a different harness major version.

Related errors

• {name} is read-only; mutate its fields instead
• unknown ProxyConfig field: {key}
• mode must be 'token' or 'cache'
• 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/49cd8421a457a917. Report an issue: GitHub.