headroomlabs-ai/headroom · warning · HTTPException

format_retrieval_miss_detail(entry_status)

Error message

format_retrieval_miss_detail(entry_status)

What it means

When the compression store reports a non-'available' status for the submitted hash (expired, evicted, or unknown), POST /v1/retrieve returns HTTP 404 with a formatted detail from format_retrieval_miss_detail explaining the specific miss. This is a normal cache-miss signal, not a server fault.

Source

Thrown at headroom/proxy/server.py:4609

        LLMs can call this endpoint to get more data if needed.

        Request body:
            hash (str): Hash key from compression marker (required)

        Response:
            {"hash": "...", "original_content": "...", ...}
        """
        data = await request.json()
        hash_key = data.get("hash")

        if not hash_key:
            raise HTTPException(status_code=400, detail="hash required")

        store = get_compression_store()

        entry_status = store.get_entry_status(hash_key, clean_expired=True)
        if entry_status["status"] != "available":
            raise HTTPException(
                status_code=404,
                detail=format_retrieval_miss_detail(entry_status),
            )

        # Retrieval is by hash: always return the full original content.
        entry = store.retrieve(hash_key)
        if entry:
            return {
                "hash": hash_key,
                "original_content": entry.original_content,
                "original_tokens": entry.original_tokens,
                "original_item_count": entry.original_item_count,
                "compressed_item_count": entry.compressed_item_count,
                "tool_name": entry.tool_name,
                "retrieval_count": entry.retrieval_count,
            }
        raise HTTPException(
            status_code=404,

View on GitHub (pinned to 322425c43b)

Solutions

1. Read the returned detail to distinguish expired/missing/evicted.
2. Retrieve promptly after compression and keep retention long enough for your session length.
3. On miss, rebuild context from the original source instead of retrying the same hash.

status = store.get_entry_status(hash_key, clean_expired=True)["status"]
if status != "available":
    handle_miss(status)  # rebuild context instead of POSTing

resp = await client.post("/v1/retrieve", json={"hash": h})
if resp.status_code == 404:
    detail = resp.json()["detail"]
    regenerate_context(detail)  # expired/missing/evicted

When it happens

Trigger: Retrieving a hash after its TTL expired, after restart/cleanup evicted the entry, with a truncated/mistyped hash, or before the original compression was stored.

Common situations: Long-running sessions resuming old compressed markers; store retention set low; mismatch between compression and retrieval environments/stores.

Related errors

• hash required
• format_retrieval_miss_detail(store.get_entry_status(hash_key
• upstream request failed: {0}
• invalid upstream URL: {0}
• metrics response build error: {e}

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