{"record":{"id":"190d795586de1138","repo":"headroomlabs-ai/headroom","slug":"unknown-compaction-format-resolved-format-r-exp","errorCode":null,"errorMessage":"unknown compaction format {resolved_format!r}; expected one of: {', '.join(_SUPPORTED_COMPACTION_FORMATS)}","messagePattern":"unknown compaction format (.+?); expected one of: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/transforms/smart_crusher.py","lineNumber":435,"sourceCode":"        # falls through to the lossy path with CCR-Dropped retrieval\n        # markers. Pass `with_compaction=False` to opt into the\n        # pre-PR4 lossy-only path (used by retention-property tests\n        # that depend on row-level item preservation).\n        #\n        # `compaction_format` picks the lossless renderer:\n        # \"csv-schema\" (default), \"json\", or \"markdown-kv\" (opt-in\n        # trade of tokens for model read accuracy). Falls back to the\n        # HEADROOM_COMPACTION_FORMAT env var when the kwarg is None.\n        # Ignored when with_compaction=False.\n        resolved_format = compaction_format or os.environ.get(\n            \"HEADROOM_COMPACTION_FORMAT\", \"csv-schema\"\n        )\n        # Validate even when with_compaction=False: an explicit bogus\n        # format (kwarg or env var) is a misconfiguration that should be\n        # visible, not silently accepted because the knob happens to be\n        # ignored on this path.\n        if resolved_format not in _SUPPORTED_COMPACTION_FORMATS:\n            raise ValueError(\n                f\"unknown compaction format {resolved_format!r}; \"\n                f\"expected one of: {', '.join(_SUPPORTED_COMPACTION_FORMATS)}\"\n            )\n        self._compaction_format = resolved_format if with_compaction else None\n        self._resolved_compaction_format = resolved_format\n        # Cache of Rust crushers keyed by lossless_only, so a per-call\n        # override builds the alternate at most once.\n        self._rust_by_lossless_only: dict[bool, Any] = {}\n        self._rust = self._build_rust(self._lossless_only)\n\n    def _build_rust(self, lossless_only: bool) -> Any:\n        \"\"\"Build (and cache) the Rust crusher for a `lossless_only` value.\"\"\"\n        cached = self._rust_by_lossless_only.get(lossless_only)\n        if cached is not None:\n            return cached\n        kwargs = dict(self._rust_cfg_kwargs)\n        kwargs[\"lossless_only\"] = lossless_only\n        rust_cfg = self._RustSmartCrusherConfig(**kwargs)","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/smart_crusher.py#L417-L453","documentation":"SmartCrusher validates the resolved compaction format (kwarg `compaction_format`, else env `HEADROOM_COMPACTION_FORMAT`, default `csv-schema`) against a fixed set of supported formats. The check runs even when compaction is disabled, because a bogus format — whether from the kwarg or the environment — is a misconfiguration that should surface immediately rather than hide behind a knob that happens to be unused on this path.","triggerScenarios":"Passing `compaction_format=\"yaml\"` (or any value outside the supported set), or exporting `HEADROOM_COMPACTION_FORMAT=json-schema` / a misspelled value like `markdwon-kv` in the environment, regardless of `with_compaction`.","commonSituations":"An old `.env`/CI variable set for a previous version whose format names changed; typos in deployment manifests (Helm values, docker-compose env); copy-pasting a format name from outdated docs.","solutions":["Use a supported value: `csv-schema` (default), `json`, or `markdown-kv` — exactly as spelled","Check the environment: `echo $HEADROOM_COMPACTION_FORMAT` and fix or unset a stale/misspelled value","Pass the kwarg explicitly (`compaction_format=\"json\"`) to override a bad inherited env value at the call site"],"exampleFix":"# before\nexport HEADROOM_COMPACTION_FORMAT=json-schema   # unsupported\ncrusher = SmartCrusher(with_compaction=True)\n\n# after\nexport HEADROOM_COMPACTION_FORMAT=json\ncrusher = SmartCrusher(with_compaction=True, compaction_format=\"json\")","handlingStrategy":"validation","validationCode":"SUPPORTED_FORMATS = {\"csv-schema\", \"json\", \"markdown-kv\"}  # mirror _SUPPORTED_COMPACTION_FORMATS\n\nresolved = compaction_format or os.environ.get(\"HEADROOM_COMPACTION_FORMAT\", \"csv-schema\")\nif resolved not in SUPPORTED_FORMATS:\n    raise ValueError(f\"unsupported compaction format {resolved!r}; valid: {sorted(SUPPORTED_FORMATS)}\")","typeGuard":"def is_supported_format(fmt: str | None) -> bool:\n    return fmt is None or fmt in {\"csv-schema\", \"json\", \"markdown-kv\"}","tryCatchPattern":"try:\n    crusher = SmartCrusher(compaction_format=fmt)\nexcept ValueError as e:\n    if \"unknown compaction format\" in str(e):\n        crusher = SmartCrusher(compaction_format=\"csv-schema\")\n    else:\n        raise","preventionTips":["Validate the env var once at process start and fail with an actionable message","Treat format names as an enum in config schemas (pydantic Literal) so bad values fail at load time","Cover the env var in deployment-config lint checks"],"tags":["configuration","env-vars","validation","smart-crusher"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}