{"record":{"id":"a67da7791597c40b","repo":"headroomlabs-ai/headroom","slug":"format-retrieval-miss-detail-entry-status","errorCode":null,"errorMessage":"format_retrieval_miss_detail(entry_status)","messagePattern":"format_retrieval_miss_detail\\(entry_status\\)","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"headroom/proxy/server.py","lineNumber":4609,"sourceCode":"        LLMs can call this endpoint to get more data if needed.\n\n        Request body:\n            hash (str): Hash key from compression marker (required)\n\n        Response:\n            {\"hash\": \"...\", \"original_content\": \"...\", ...}\n        \"\"\"\n        data = await request.json()\n        hash_key = data.get(\"hash\")\n\n        if not hash_key:\n            raise HTTPException(status_code=400, detail=\"hash required\")\n\n        store = get_compression_store()\n\n        entry_status = store.get_entry_status(hash_key, clean_expired=True)\n        if entry_status[\"status\"] != \"available\":\n            raise HTTPException(\n                status_code=404,\n                detail=format_retrieval_miss_detail(entry_status),\n            )\n\n        # Retrieval is by hash: always return the full original content.\n        entry = store.retrieve(hash_key)\n        if entry:\n            return {\n                \"hash\": hash_key,\n                \"original_content\": entry.original_content,\n                \"original_tokens\": entry.original_tokens,\n                \"original_item_count\": entry.original_item_count,\n                \"compressed_item_count\": entry.compressed_item_count,\n                \"tool_name\": entry.tool_name,\n                \"retrieval_count\": entry.retrieval_count,\n            }\n        raise HTTPException(\n            status_code=404,","sourceCodeStart":4591,"sourceCodeEnd":4627,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/server.py#L4591-L4627","documentation":"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.","triggerScenarios":"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.","commonSituations":"Long-running sessions resuming old compressed markers; store retention set low; mismatch between compression and retrieval environments/stores.","solutions":["Read the returned detail to distinguish expired/missing/evicted.","Retrieve promptly after compression and keep retention long enough for your session length.","On miss, rebuild context from the original source instead of retrying the same hash."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"status = store.get_entry_status(hash_key, clean_expired=True)[\"status\"]\nif status != \"available\":\n    handle_miss(status)  # rebuild context instead of POSTing","typeGuard":null,"tryCatchPattern":"resp = await client.post(\"/v1/retrieve\", json={\"hash\": h})\nif resp.status_code == 404:\n    detail = resp.json()[\"detail\"]\n    regenerate_context(detail)  # expired/missing/evicted","preventionTips":["Retrieve soon after compression.","Size retention/TTL to session length.","Log miss details to tune expiry."],"tags":["http","cache","retrieval"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}