Troubleshooting

Troubleshooting

Set log_level: 'INFO' in config.yaml to get a timestamped config/debug.log next to your config. Container output is available with docker compose logs -f supportbot.

---

Bot Doesn't Start / Crashes on Startup

Symptom	Cause	Fix
Please change your bot token in config/config.yaml	bot_token still YOUR_BOT_TOKEN	Put the token from @BotFather into config/config.yaml
Container exits immediately	Invalid config.yaml syntax	Validate YAML: python3 -c "import yaml; yaml.safe_load(open('config/config.yaml'))"
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017	Wrong mongodb_uri / MongoDB not reachable	In Docker use mongodb://mongodb:27017/support; verify the MongoDB container is running
tsc: The TypeScript Compiler … help text, then exit	Old image running npm run prod before v5 (re-compiled at runtime)	Upgrade to v5.0.0 — prod now runs the compiled build/index.js
Cannot read properties of undefined (reading 'back')	Bot < v5.0.0 with a config that has no language: block	Upgrade — defaults are now always merged. On older versions add a language: block from the sample.
getaddrinfo EAI_AGAIN api.telegram.org	DNS broken on the host / in Docker	Check /etc/resolv.conf of the host; restart the container after fixing DNS

---

Messages Not Forwarded to Staff Group

Symptom	Cause	Fix
Tickets go nowhere	Wrong staffchat_id	Send /id in the group (or use @bostrot_bot); supergroup ids are negative and start with -100
Bot can't send messages	Bot not added as admin	Add the support bot as admin of the staff group (not just member)
Ticket "arrives" (log shows Ticket #T…) but nobody sees it	Staff group has Topics enabled — tickets go to the General topic	Unhide the General topic, or use a group without topics
First message of a new user never arrived (older versions)	Race between ticket creation and forwarding	Fixed in v5.0.0
User receives undefined as confirmation (older versions)	language.confirmationMessage missing from config	Fixed in v5.0.0 (defaults are merged, legacy contactMessage is honoured). On older versions add confirmationMessage to language:
can't parse entities in the log	Message text contains characters invalid for the parse mode	User text is escaped automatically; for your own language strings see Markdown
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'

---

Auto-reply / LLM Not Working

Symptom	Cause	Fix
Keyword rules don't trigger	Question text doesn't appear in the user message	Rules use substring matching — make sure the question string appears in the user's message
LLM never answers, log shows LLM returned no answer	llm_knowledge is empty or does not cover the question	The model only answers from the knowledge base. Fill llm_knowledge (the bot warns at startup when it is empty).
Error in LLM response: AuthenticationError: 401	Wrong llm_api_key for the endpoint	Check the key on your provider / LiteLLM proxy; the sample key is a placeholder
Error in LLM response: … model not found	llm_model not available at llm_base_url	Use a model name your provider/proxy actually serves
Auto-replied tickets don't show up for staff	show_auto_replied: false	Set it to true (enabled automatically with use_llm)

---

Categories Not Showing Up

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

---

Signal Integration Issues

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
Host disk fills up over time	signal-cli extracts libsignal* into /tmp on every restart	Clean /tmp/libsignal* in the container (keep the newest) or mount a tmpfs on /tmp

---

Web Chat Widget Issues

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
Users get an "offline" message	web_chat.business_hours active	Adjust start/end/timezone or set enabled: false — business hours apply to all channels

---

Docker / Container Issues

Symptom	Cause	Fix
Port conflict on 8080	Another service using the same port	Change web_server_port and the port mapping in docker-compose.yml
Can't reach MongoDB / mongo-express from another machine	Ports are bound to 127.0.0.1 on purpose	Use an SSH tunnel, or change the mapping if you really need external access
MongoDB container won't start	Insufficient disk space	Check available disk: df -h
Container uses too much memory	Workload exceeds limits	Add deploy.resources.limits.memory in docker-compose.yml for affected containers

---

General Debugging Tips

• Check bot logs: docker compose logs --tail=100 supportbot
• Enable the debug file: log_level: 'INFO' → config/debug.log
• Verify config syntax: paste your config.yaml into a YAML validator
• Test MongoDB connection: mongosh "mongodb://localhost:27017/support" — if this connects, the URI is valid
• Check the bot itself: curl https://api.telegram.org/bot<TOKEN>/getMe and …/getWebhookInfo (a set webhook blocks long polling)
• Telegram Bot API status: https://t.me/BotNews