Troubleshooting

Bot Doesn't Start / Crashes on Startup

Symptom	Cause	Fix
Container exits immediately	Invalid `config.yaml` syntax	Validate YAML: `python3 -c "import yaml; yaml.safe_load(open('config/telegram-bot/config.yaml'))"`
Error connecting to MongoDB	Wrong connection string or credentials	Verify `mongodb_uri`, ensure MongoDB container is running and accessible
Bot token error	Invalid or revoked Telegram bot token	Check token in `bot_token` field, verify the bot exists via @BotFather

Symptom	Cause	Fix
Tickets go nowhere	Wrong `staffchat_id`	Verify the group ID — use a "Show Chat ID" bot in your group to confirm
Bot can't send messages	Bot not added as admin	Add the support bot as admin of the staff group (not just member)
Messages arrive but formatting is broken	Wrong `parse_mode` for chat type	If using Signal, set `staffchat_parse_mode: 'plaintext'`. For Telegram, use `'MarkdownV2'` or `'HTML'`

Symptom	Cause	Fix
Keyword rules don't trigger	Question text doesn't match user message	Rules use substring matching — make sure the `question` string appears in the user's message (case-insensitive)
LLM replies not generated	Missing or invalid API key	Verify `llm_api_key`, check `llm_base_url` is reachable, ensure `use_llm: true`
LLM returns errors	Model not available at endpoint	Check LiteLLM proxy logs, verify the model name matches what your provider offers

Symptom	Cause	Fix
User sees no category keyboard	`categories` array is empty or missing	Add at least one category entry in config
Messages go to wrong group	Wrong `group_id` for a category	Verify each category's `group_id` — must be a supergroup ID (negative, `-100` prefixed)
Bot not receiving messages in category groups	Bot not admin in those groups	Add the bot as admin of every group listed in categories

Symptom	Cause	Fix
QR code doesn't load	signal-cli container still starting	Wait 1-2 minutes after container start, then refresh
Can't link device via QR	Number already linked elsewhere	Unregister the number in signal-cli first: `POST /v1/unregister/{number}` on the REST API
Messages sent but not received by Signal	Wrong `signal_number` format	Must include country code with `+` prefix (e.g., `"+14155551234"`)
Formatting shows Markdown syntax literally	Using Markdown parse mode with Signal	Set `staffchat_parse_mode: 'plaintext'` — Signal doesn't support Markdown

Symptom	Cause	Fix
Widget doesn't load on website	Wrong server IP or port in script URL	Verify `web_server_port` matches the URL, ensure firewall allows inbound traffic on that port
Mixed content warning (HTTPS site)	Loading widget over HTTP	Configure SSL with `web_server_ssl_cert` and `web_server_ssl_key`, use `https://` in script source
Messages from web chat not reaching staff	Bot crashed or misconfigured	Check bot logs, verify `staffchat_id` is set correctly

Symptom	Cause	Fix
Port conflict on 8080	Another service using the same port	Change `web_server_port` or adjust the port mapping in docker-compose.yml
MongoDB container won't start	Insufficient disk space	Check available disk: `df -h`. MongoDB data directory needs free space.
Container uses too much memory	Default limits exceeded by workload	Increase `deploy.resources.limits.memory` in docker-compose.yml for affected containers

Check bot logs: docker compose logs --tail=50 telegram-support-bot (or your container name)
Verify config syntax: Copy your config.yaml into a YAML validator online
Test MongoDB connection: mongosh "mongodb://your-user:password@localhost:27017/telegram" — if this connects, the URI is valid
Check Telegram Bot API status: Visit https://t.me/BotNews for outage announcements

Please tell me if something is missing in this guide or should be added — open an issue on GitHub.