Runbook: Troubleshooting & Operations¶

This runbook provides solutions for common issues and a collection of useful commands for operating the Cloudflare RAG worker.

1. Troubleshooting Common Issues¶

Symptom	Potential Cause	Resolution Steps
`vectorize_binding: false` in `/rag/health`	The worker is not correctly bound to the Vectorize index.	1. Verify that the `"vectorize"` key is a top-level entry in `wrangler.jsonc`. 2. Ensure the `index_name` in `wrangler.jsonc` matches the actual index name. 3. Redeploy the worker or restart your `wrangler dev --remote` session.
`429 rate_limited` from AI Gateway	The upstream provider's (e.g., OpenAI) rate limit has been exceeded.	1. Treat this as a `rate_limited` status, not a `down` status. 2. For health checks, rely on the default `/models` probe, which is cached by the gateway. 3. Ensure Cache responses is enabled in the AI Gateway settings to minimize upstream calls.
Vector search with `lang: "ar"` returns 0 results	The `published_at_bucket` filter might be incorrect, or metadata is missing.	1. Double-check that the `published_at_bucket` filter uses the `YYYYMM` format (e.g., `202508`), not `YYYYMMDD`. 2. Verify that the vectors in the index have the correct `lang` metadata.
Reranking step is not running	The vector's metadata is missing the text snippet required for reranking.	Ensure that the `metadata` object for each vector includes a `text`, `snippet`, or `content` field containing the text to be reranked.

2. Useful One-Liners¶

Inspecting Vectorize¶

# List all Vectorize indexes in your account
wrangler vectorize list

# List the metadata configuration for the dev index
wrangler vectorize list-metadata-index labeeb-articles-dev

Local & Remote Testing¶

# Check bindings and health of a remote dev session
wrangler dev --remote
curl -s http://127.0.0.1:8787/rag/health | jq

# Send a smoke test query to a deployed worker
curl -s -X POST https://<your-worker-url>/rag/query \
 -H 'content-type: application/json' \
 -d '{"query":"وقف إطلاق النار","filters":{"lang":"ar"},"k":5}' | jq

# Test the protected LLM chat endpoint
curl -s -X POST https://<your-worker-url>/llm/chat \
 -H 'x-api-key: <your-api-key>' \
 -H 'content-type: application/json' \
 -d '{"messages":[{"role":"user","content":"Say hi in 5 words."}]}' | jq