headroomlabs-ai/headroom · error · ValueError

unknown compaction format {resolved_format!r}; expected one

Error message

unknown compaction format {resolved_format!r}; expected one of: {', '.join(_SUPPORTED_COMPACTION_FORMATS)}

What it means

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.

Source

Thrown at headroom/transforms/smart_crusher.py:435

        # falls through to the lossy path with CCR-Dropped retrieval
        # markers. Pass `with_compaction=False` to opt into the
        # pre-PR4 lossy-only path (used by retention-property tests
        # that depend on row-level item preservation).
        #
        # `compaction_format` picks the lossless renderer:
        # "csv-schema" (default), "json", or "markdown-kv" (opt-in
        # trade of tokens for model read accuracy). Falls back to the
        # HEADROOM_COMPACTION_FORMAT env var when the kwarg is None.
        # Ignored when with_compaction=False.
        resolved_format = compaction_format or os.environ.get(
            "HEADROOM_COMPACTION_FORMAT", "csv-schema"
        )
        # Validate even when with_compaction=False: an explicit bogus
        # format (kwarg or env var) is a misconfiguration that should be
        # visible, not silently accepted because the knob happens to be
        # ignored on this path.
        if resolved_format not in _SUPPORTED_COMPACTION_FORMATS:
            raise ValueError(
                f"unknown compaction format {resolved_format!r}; "
                f"expected one of: {', '.join(_SUPPORTED_COMPACTION_FORMATS)}"
            )
        self._compaction_format = resolved_format if with_compaction else None
        self._resolved_compaction_format = resolved_format
        # Cache of Rust crushers keyed by lossless_only, so a per-call
        # override builds the alternate at most once.
        self._rust_by_lossless_only: dict[bool, Any] = {}
        self._rust = self._build_rust(self._lossless_only)

    def _build_rust(self, lossless_only: bool) -> Any:
        """Build (and cache) the Rust crusher for a `lossless_only` value."""
        cached = self._rust_by_lossless_only.get(lossless_only)
        if cached is not None:
            return cached
        kwargs = dict(self._rust_cfg_kwargs)
        kwargs["lossless_only"] = lossless_only
        rust_cfg = self._RustSmartCrusherConfig(**kwargs)

View on GitHub (pinned to 322425c43b)

Solutions

1. Use a supported value: `csv-schema` (default), `json`, or `markdown-kv` — exactly as spelled
2. Check the environment: `echo $HEADROOM_COMPACTION_FORMAT` and fix or unset a stale/misspelled value
3. Pass the kwarg explicitly (`compaction_format="json"`) to override a bad inherited env value at the call site

Example fix

# before
export HEADROOM_COMPACTION_FORMAT=json-schema   # unsupported
crusher = SmartCrusher(with_compaction=True)

# after
export HEADROOM_COMPACTION_FORMAT=json
crusher = SmartCrusher(with_compaction=True, compaction_format="json")

SUPPORTED_FORMATS = {"csv-schema", "json", "markdown-kv"}  # mirror _SUPPORTED_COMPACTION_FORMATS

resolved = compaction_format or os.environ.get("HEADROOM_COMPACTION_FORMAT", "csv-schema")
if resolved not in SUPPORTED_FORMATS:
    raise ValueError(f"unsupported compaction format {resolved!r}; valid: {sorted(SUPPORTED_FORMATS)}")

def is_supported_format(fmt: str | None) -> bool:
    return fmt is None or fmt in {"csv-schema", "json", "markdown-kv"}

try:
    crusher = SmartCrusher(compaction_format=fmt)
except ValueError as e:
    if "unknown compaction format" in str(e):
        crusher = SmartCrusher(compaction_format="csv-schema")
    else:
        raise

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

• auth_style must be 'post' or 'basic'
• bedrock_eventstream_parse_failed
• Unknown provider: {self.llm_config.provider}
• HEADROOM_LEARN_CLI={cli_override!r} is not a supported CLI.
• max_size must be at least 1, got {max_size}

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