Skip to content

Troubleshooting

Quick Diagnostics

simplecontext-bot status --test

This checks engine, agents, Telegram token, LLM connection, and reports any issues.

Common Issues

Bot doesn't start

Check: 

simplecontext-bot status

Fix: 

# Reconfigure
simplecontext-bot setup

# Or start fresh
rm -rf ~/.simplecontext-bot
simplecontext-bot setup

LLM errors

❌ Invalid API key 

simplecontext-bot setup
# Re-enter your API key at Step 5

⚠️ Rate limit reached

You've hit the API rate limit. Wait a moment, then try again. Consider switching to a different model or provider.

❌ Connection error

Check your internet connection. For Ollama: make sure Ollama is running (ollama serve).

Agents not loading

Symptoms: Bot responds with general agent for everything, or /agents shows an empty list.

# Check if agents are installed
simplecontext-bot status

# Reinstall agents
simplecontext-bot update --agents-only

Plugin not loading

Symptoms: Plugin not in /plugins, plugin commands missing from /help.

Check the plugin file: 

python3 -c "
import sys
sys.path.insert(0, '/path/to/simplecontext')
from vector_search_plugin import VectorSearchPlugin
print(VectorSearchPlugin)
"

Check logs: 

simplecontext-bot start --debug
# Look for: "Gagal load plugin" or "Tidak ada BasePlugin class"

Common causes: - Plugin file has a syntax error - Plugin class doesn't inherit BasePlugin - Plugin class doesn't have a name attribute - Import error in plugin file

Memory not persisting

Symptoms: Bot forgets everything on restart.

Check that bot.db exists: 

ls ~/.simplecontext-bot/bot.db

If missing, the storage path may be wrong: 

simplecontext-bot status
# Check: storage path

Agents hot-reload not working

Hot-reload watches the agents/ folder for file changes. Make sure:

  1. hot_reload: true in config (check ~/.simplecontext-bot/config.json)
  2. You're editing files in the right folder: ~/.simplecontext-bot/agents/

/semantic command not available

The /semantic command requires the vector-search plugin:

simplecontext-bot plugins install vector-search
simplecontext-bot start   # restart to register the command

Reset and Start Fresh

rm -rf ~/.simplecontext-bot
simplecontext-bot setup

This removes all config, memory, agents, and plugins. Run setup again from scratch.

Debug Logging

simplecontext-bot start --debug

Debug mode logs: - Agent routing decisions - Context retrieval pipeline (candidates, scores, selection) - Plugin hook calls - LLM request/response

Getting Help