Troubleshooting

401 Unauthorized

Symptom: JSON body with error: "Unauthorized" and onboarding URL.

Cause: Non-empty Authorization that is not a valid admin bearer (member seam returns null). Empty/missing Authorization is public, not 401.

Fix:

1. For public tools: omit the Authorization header entirely.
2. For admin tools: send Authorization: Bearer <ADMIN_API_TOKEN>.
3. Check for extra spaces, wrong environment, or accidental dummy Bearer values.

405 Method Not Allowed

Symptom: Body like MCP endpoint - POST JSON-RPC only.

Cause: Client issued GET (SSE) or another method.

Fix: Use POST with a JSON-RPC body. Stateless JSON response mode only.

empty 202

Symptom: No JSON body, status 202.

Cause: Notification-only request (no id), e.g. notifications/initialized.

Fix: Expected. Follow with tools/list or tools/call that include an id.

unknown tool

Symptom: JSON-RPC error or tool result unknown tool: ...

Cause: Typo, planned-but-unshipped name, or admin-only tool under public principal.

Fix: Call tools/list without auth for the public catalog; with admin bearer for ops tools.

bot-proxy not configured

Symptom: Tool JSON mentions bot-proxy / BOT_SERVICE_URL / ADMIN_API_TOKEN absent.

Cause: Vercel lacks bot proxy env for admin tools.

Fix (operators): Set BOT_SERVICE_URL and ADMIN_API_TOKEN on Vercel. Public tools still work without that pair.

thin travel inventory

Symptom: search_stay_packages returns honesty envelope / empty packages.

Cause: Real inventory thin for origin/nights/budget - not a protocol failure.

Fix: Broaden dates/budget/nights; do not invent listings.