headroomlabs-ai/headroom · info · HTTPException

No TOIN pattern found with hash starting with: {hash_prefix}

Error message

No TOIN pattern found with hash starting with: {hash_prefix}

What it means

GET /v1/toin/patterns/{hash_prefix} returns HTTP 404 when no learned TOIN pattern matches the supplied hash prefix. Prefix lookup only matches patterns already collected by the Tool Output Intelligence Network store.

Source

Thrown at headroom/proxy/server.py:4918

        exported = toin.export_patterns()
        patterns_data = exported.get("patterns", {})

        # Search for pattern with matching hash prefix
        for sig_hash, pattern_dict in patterns_data.items():
            if sig_hash.startswith(hash_prefix):
                # Keep this response aligned with /v1/toin/patterns while
                # excluding query text, field semantics, and other internal
                # learning state from the detail endpoint.
                return {
                    "compressions": pattern_dict.get("total_compressions", 0),
                    "retrievals": pattern_dict.get("total_retrievals", 0),
                    "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
                    "confidence": pattern_dict.get("confidence", 0.0),
                    "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
                    "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
                }

        raise HTTPException(
            status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
        )

    @app.get("/v1/retrieve/{hash_key}", dependencies=[Depends(_require_loopback)])
    async def ccr_retrieve_get(hash_key: str):
        """GET version of CCR retrieve for easier testing."""
        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:

View on GitHub (pinned to 322425c43b)

Solutions

1. Check /v1/toin/stats to confirm patterns exist at all.
2. Use the exact prefix reported by pattern-listing endpoints.
3. Run representative tool workloads first so patterns are learned.

stats = (await client.get("/v1/toin/stats")).json()
if not stats.get("total_patterns", 0):
    skip_pattern_lookup(prefix)

resp = await client.get(f"/v1/toin/patterns/{prefix}")
if resp.status_code == 404:
    handle_no_pattern(prefix)

When it happens

Trigger: Querying a prefix with no learned patterns, a too-short/ambiguous prefix that matched nothing, or a pattern DB that is empty after a fresh start or reset.

Common situations: New deployments before enough tool traffic; querying after the learning store was cleared; environment mismatch between collection and query.

Related errors

• No telemetry found for signature: {signature_hash}
• upstream request failed: {0}
• invalid upstream URL: {0}
• metrics response build error: {e}
• Copilot token exchange failed with HTTP {exc.code}: {body}

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