{"record":{"id":"95a49f6aef8699b1","repo":"headroomlabs-ai/headroom","slug":"unknown-headroomconfig-field-key","errorCode":null,"errorMessage":"unknown HeadroomConfig field: {key}","messagePattern":"unknown HeadroomConfig field: (.+?)","errorType":"exception","errorClass":"AttributeError","httpStatus":null,"severity":"error","filePath":"headroom/testing/harness.py","lineNumber":738,"sourceCode":"    Configure = configure\n\n    def configure_proxy(self, callback: ProxyCallback | None = None, **overrides: Any) -> Headroom:\n        if callback is not None:\n            callback(self._proxy_config)\n        for key, value in overrides.items():\n            if not hasattr(self._proxy_config, key):\n                raise AttributeError(f\"unknown ProxyConfig field: {key}\")\n            setattr(self._proxy_config, key, value)\n        return self\n\n    ConfigureProxy = configure_proxy\n\n    def configure_headroom(self, callback: SdkCallback | None = None, **overrides: Any) -> Headroom:\n        if callback is not None:\n            callback(self._headroom_config)\n        for key, value in overrides.items():\n            if not hasattr(self._headroom_config, key):\n                raise AttributeError(f\"unknown HeadroomConfig field: {key}\")\n            setattr(self._headroom_config, key, value)\n        return self\n\n    ConfigureHeadroom = configure_headroom\n\n    def with_compression(\n        self,\n        *,\n        mode: Literal[\"token\", \"cache\"] | None = None,\n        kompress: bool | None = None,\n        force_kompress_all: bool | None = None,\n        lossless: bool | None = None,\n        compressors: set[str] | Sequence[str] | Literal[\"*\"] | None = None,\n        min_tokens: int | None = None,\n        max_items: int | None = None,\n        savings_profile: str | None = None,\n    ) -> Headroom:\n        \"\"\"Configure proxy and SDK compression posture with real config fields.\"\"\"","sourceCodeStart":720,"sourceCodeEnd":756,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/testing/harness.py#L720-L756","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If the option controls the proxy (mode, optimize, port, ...), move it to configure_proxy(...)/ConfigureProxy(...).","If upgrading headroom, diff the changelog for renamed HeadroomConfig fields and update the call.","Guard programmatically: build the overrides dict and filter with hasattr(config, key) before calling."],"exampleFix":"# before\nheadroom.configure_headroom(context_window=200_000, mode=\"token\")\n\n# after\nheadroom.configure_headroom(context_window=200_000)\nheadroom.configure_proxy(mode=\"token\")","handlingStrategy":"validation","validationCode":"from dataclasses import fields\nvalid = {f.name for f in fields(type(harness._headroom_config))}\noverrides = {k: v for k, v in overrides.items() if k in valid}\nmissing = set(overrides) - set(valid)","typeGuard":"def is_valid_headroom_override(key: str) -> bool:\n    return hasattr(harness._headroom_config, key)","tryCatchPattern":"try:\n    headroom.configure_headroom(**overrides)\nexcept AttributeError as e:\n    if \"unknown HeadroomConfig field\" in str(e):\n        key = str(e).rsplit(\":\", 1)[1].strip()\n        raise ConfigError(f\"bad headroom override {key!r}; valid: {headroom_config_fields()}\") from e\n    raise","preventionTips":["Build overrides as a dict validated against HeadroomConfig fields instead of inline kwargs.","Keep headroom options and proxy options in separate configure_* calls.","Pin the headroom version and re-read config docs after upgrades."],"tags":["config","sdk","fluent-api","typo"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}