headroomlabs-ai/headroom · warning · HTTPException

format_retrieval_miss_detail(store.get_entry_status(hash_key

Error message

format_retrieval_miss_detail(store.get_entry_status(hash_key, clean_expired=True))

What it means

The fallback branch of POST /v1/retrieve returns HTTP 404 with format_retrieval_miss_detail when store.retrieve() returns no entry even though the earlier status check said 'available', a rare race where the entry expires between check and read. The detail is computed from a fresh get_entry_status call.

Source

Thrown at headroom/proxy/server.py:4626

        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,
            detail=format_retrieval_miss_detail(
                store.get_entry_status(hash_key, clean_expired=True)
            ),
        )

    @app.get("/v1/retrieve/stats", dependencies=[Depends(_require_loopback)])
    async def ccr_stats():
        """Get CCR compression store statistics."""
        store = get_compression_store()
        stats = store.get_stats()
        events = store.get_retrieval_events(limit=20)
        return {
            "store": stats,
            "recent_retrievals": [
                {
                    "hash": e.hash,
                    "query": e.query,

View on GitHub (pinned to 322425c43b)

Solutions

1. Retry retrieval once on 404 immediately after a successful compression.
2. Increase retention/TTL so markers outlive their sessions.
3. Treat 404 as 'gone'; recompute or re-compress the context.

for attempt in range(2):
    resp = await client.post("/v1/retrieve", json={"hash": h})
    if resp.status_code != 404:
        break
else:
    regenerate_context()  # entry truly gone

When it happens

Trigger: Entry TTL elapsing or eviction happening between get_entry_status and store.retrieve within one request; concurrent cleanup running during retrieval.

Common situations: Aggressive expiry timers; heavy parallel retrievals of the same marker; store compaction mid-request.

Related errors

• format_retrieval_miss_detail(entry_status)
• upstream request failed: {0}
• invalid upstream URL: {0}
• metrics response build error: {e}
• offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch require

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