Troubleshooting

This chapter is a symptom index. Find what you see, check the listed item, and follow the link to the chapter section that holds the fix.

Where to look first

Check that LiteBot is up and can reach its database:
```
curl -s http://127.0.0.1:3345/health/ready
curl -s http://127.0.0.1:3345/health/detail
```
/health does not test any LLM provider; a green health check does not mean bots can answer. See Health probes.
Read the last 200 log lines around the time of the problem:
```
pm2 logs litebot --lines 200 --nostream
```
See Logs for files and levels.

For one conversation, read what was stored and what each turn did:

curl -s http://127.0.0.1:3345/api/conversations/<sessionId>/traces -H "Authorization: Bearer <token>"

What you see	Likely cause	Check this	Fix
Process exits at start with a JWT message	`JWT_SECRET` missing or shorter than 32 characters	`.env` beside the binary	Minimal .env, JWT_SECRET
Starts, but settings in `.env` are ignored, or the dashboard returns 404	pm2 started the binary from another directory; `.env` and `public/` are read from the working directory	`pm2 describe litebot` shows `exec cwd`	Run under pm2
Data lands in the wrong database	The database name inside `MONGODB_URI` is ignored	`MONGODB_DB_NAME` (default `bitvoice_bot`)	MongoDB
Knowledge base errors at start, Milvus connection refused	`VECTOR_DB_PROVIDER` unset; the code default is `milvus`, not `vectra`	`VECTOR_DB_PROVIDER` in `.env`	Vector database
A dashboard page is missing	The page's `VITE_*` flag was off when the bundle was built	Which bundle you deployed	Feature flags
A page opens but every action returns 403	The page is shown to roles that lack the permission	The user's role and its permissions	Built-in roles

What you see	Likely cause	Check this	Fix
Bot from a JSON file never appears	A key not in the schema (for example `promptFile`, `voice.thinkingBudget`) makes the loader skip the bot	Log line for that bot id at start	The unknown-key rule, Keys the loader reads but the schema rejects
File edit has no effect	A Mongo copy of the bot wins by id at every load	`bots` collection for that id	Where bots come from
Direct Mongo edit has no effect	Bots are read from Mongo only at load	—	Reloading and hot reload
Prompt shows `{{clinic_name}}` literally	Placeholders are filled for file bots at load, not for bots saved from the dashboard or API	Where the bot came from	Variables
Conversation moves to another bot mid-session	The intent router switched bots; it ignores a `botId` pinned in the request	Router settings, `switchingThreshold`	Routing and bot switching
Flow bot previews well but misbehaves once saved	The runtime does not read the node types the editor saves	Node types in `_visualFlow`	Known gaps

What you see	Likely cause	Check this	Fix
"All LLM providers failed" after a short provider outage	Provider marked unhealthy and never retried (older builds)	Log lines marking the provider unhealthy	Health and recovery, Provider health and recovery
Substitute provider returns 400	The bot's model name was sent to a provider that does not have it	Provider and model in the error	Model name on a substitute
Requests hang for a long time	`ENABLE_CIRCUIT_BREAKER` unset: model and tool calls have no timeout	`ENABLE_CIRCUIT_BREAKER`, `CIRCUIT_BREAKER_TIMEOUT`	Timeouts and the circuit breaker
Gemini bot fails on every call with a model error	`GEMINI_MODEL` unset falls back to a retired model	`GEMINI_MODEL`, bot `model`	Gemini (AI Studio)
One tenant's bots fail, others work	Tenant key wrong, or unreadable after `JWT_SECRET` changed (falls back to global keys)	Tenant provider keys	Per-tenant provider keys
Gateway or integration gets HTTP 429	Production rate limit per IP also covers `/api/chat`	Requests per 15 minutes from that IP	Rate and size limits, Errors and rate limits

What you see	Likely cause	Check this	Fix
Tool file in `config/tools/` not listed	An export other than the allowed ones; `require()` of an npm package	Exports in the file	The tool file, Rules for the binary
Edited disk tool still runs old code	Production does not hot-reload tool files	`NODE_ENV`	When changes take effect
Slow webhook tool reports failure but the record was created	Timeout shorter than the webhook; `CIRCUIT_BREAKER_TIMEOUT` overrides `metadata.timeout`	Tool timeout settings	Timeouts and caching
Model calls tools it should not have	The bot's `tools` list is empty, which offers every tool the tenant can see	Bot `tools`	Tools
Tool says success but nothing happened	Success gated on HTTP 200 instead of a business result	The tool's return branches	Return values

What you see	Likely cause	Check this	Fix
Log says the hook ran with success, but nothing arrived	That flag is the wrapper's, not the tool's result	The tool's own log line	Reading the log
Hook never runs	Realtime `/voice` sessions, restarts and WebSocket closes before the idle sweep do not fire hooks	How the session ended	When hooks do not fire
Hook tool rejects its parameters	A parameter is marked required	`parameters.required`	Declare every parameter, require none

What you see	Likely cause	Check this	Fix
Search returns nothing after changing the embeddings model	Stored vectors were made by the old model	Embeddings settings	Changing the embeddings model
Long text added by API matches poorly	`POST /api/documents` stores the whole text as one vector	How the text was added	Add text
First searches after a restart are slow	Warm-up not finished	Start-up log	Startup warm-up

What you see	Likely cause	Check this	Fix
`/voice` connection closes at once	Missing or invalid `token` / `api_key`, or bot has no voice settings	Close code	Errors, Enable voice on a bot
Campaign will not start	No gateway endpoint at any level	Campaign, Settings, `AUTO_DIALER_OUTBOUND_ENDPOINT`	Gateway endpoint
Answered calls listed as failed	Gateway reports a stale final status	Call tracking settings	Outcomes, Call tracking
Voice or model chosen in the campaign is not used	Realtime engine selected, or the id belongs to another provider	Engine and provider	Voices and models

Security Environment (1 of 2)