Troubleshooting

Start here when something doesn't work. Each entry is a symptom you'd actually see, with the fix underneath.

Two things to try before anything else:

lesysbot            # status screen: is the model reachable? is the service up?
                    # where is the config? how many tools are enabled?

lesysbot chat -v      # same chat, but with the log on screen

The status screen answers most "why isn't it working" questions in one look.

Talking to it#

"LLM unavailable: …"#

The model backend isn't reachable. Check it directly:

curl http://localhost:11434/         # Ollama → "Ollama is running"
ollama list                          # is your configured model here?

• Ollama not running → start it (ollama serve, or launch the app on macOS/Windows).
• Model not in the list → ollama pull <name>, or fix llm.model in ~/.lesysbot/config.yaml.
• Using a remote backend → check llm.base_url ends in /v1 and the key is right.

Slash commands (/disk_usage path=/) keep working while the model is down — they never touch it.

It picked the wrong tool, or didn't use one at all#

Smaller models call tools unreliably. In order of effectiveness:

1. Use a stronger model — see Choosing a model. Tool calling is the single thing model size helps most with here.
2. Be more specific: "check the temperature of the CPU" beats "how is it".
3. Call the tool yourself with /tool_name, which never involves the model.

The first reply takes forever#

The model is loading into memory. Later replies are much faster. ollama ps shows what's currently loaded; a model unloads after a few idle minutes.

I sent a second message and nothing happened#

Each conversation advances one turn at a time, so a message sent while the bot is still working waits for the current answer before it starts. Nothing is dropped — you'll get both replies, in order. This is most noticeable when a confirmation prompt is sitting unanswered: that turn stays open until you tap a button (or it times out after five minutes), and anything you type meanwhile queues behind it. Answer the prompt, or run the tool yourself with /tool_name — slash commands skip the queue entirely and work even mid-turn.

It forgot what we were talking about#

History is trimmed past agent.max_history (default 50 messages), and /clear wipes it. Raise the limit in Settings if your model has room for it.

Tools#

A tool isn't in /help#

• Is the file in the right folder? For an installed setup that's ~/.lesysbot/tools/, not the repo you cloned. lesysbot (the status screen) prints the path it's actually loading from.
• Files and folders starting with _ are skipped on purpose.
• An import error keeps the file from loading. Check the log: tail -n 50 ~/.lesysbot/logs/lesysbot.log.
• If mcp.hot_reload is off, restart the bot.

A tool is listed but refuses to run#

'gpu_temp' is unavailable on this machine — requires 'nvidia-smi' on PATH (not found).

That's by design: tools declare which OSes and programs they need, and say so rather than failing cryptically. Install the missing program, or use a tool that fits this machine.

'gpu_temp' is disabled.

Turn it back on: lesysbot enable gpu_temp.

lesysbot install fails#

Installing and starting#

lesysbot: command not found#

Almost always the shell you're in was started before the command existed. Open a new terminal, or:

export PATH="$HOME/.local/bin:$PATH"

The installer puts the command in ~/.local/bin and adds that directory to your ~/.profile, ~/.bashrc and ~/.zshenv. If it still isn't found there, either the installer ran with --no-modify-path (or LESYSBOT_NO_MODIFY_PATH) and added nothing, or you installed some other way — pipx and pip --user put it in their own directory:

python -m site --user-scripts     # e.g. /home/you/.local/bin

On Windows the PATH entry is set for your user account, so only new terminals see it. If you installed Python by hand, re-run its installer and tick Add Python to PATH.

PowerShell refuses to run the installer#

powershell -ExecutionPolicy Bypass -Command "irm https://lesysbot.github.io/install.ps1 | iex"

Edits to the code or a tool seem to do nothing#

A non-editable install elsewhere may be shadowing your checkout:

python -c "import lesysbot; print(lesysbot.__file__)"

If that doesn't point at your repo, re-run pip install -e ..

Running in the background#

The service starts, then exits immediately#

Read the real error first:

journalctl --user -u lesysbot -n 50            # Linux
tail -n 50 ~/Library/Logs/lesysbot/stderr.log  # macOS

Windows: Task Scheduler history, or Event Viewer → Windows Logs → Application.

Common causes:

• The model backend wasn't up yet when the service started.
• Wrong working directory — the service must run from the folder holding config.yaml and tools/, normally ~/.lesysbot.
• A wrong or revoked Telegram/Discord token.

"Another instance is already running"#

Only one copy of a Telegram or Discord bot can poll at a time (Telegram rejects both otherwise), so LeSysBot takes a lock and refuses the second, naming the PID that holds it. Stop the service first:

systemctl --user stop lesysbot          # Linux

A terminal chat (lesysbot chat) doesn't poll, so it always runs fine alongside the service.

Config changes don't take effect#

Most settings are read at startup. Restart the service:

systemctl --user restart lesysbot                                 # Linux
launchctl kickstart -k gui/$(id -u)/com.lesysbot.lesysbot         # macOS
Stop-ScheduledTask -TaskName LeSysBot; Start-ScheduledTask -TaskName LeSysBot   # Windows

Enabling and disabling tools is the exception — that applies within a second, no restart needed.

Telegram and Discord#

Full setup for both: Telegram & Discord.

Control panel and dashboards#

A few dashboard panels are empty#

The dashboard is built for your machine: each start script checks what the host can actually report, and leaves out panels nothing could fill. So an empty panel is meaningful — it means a reading you should be getting isn't arriving. Work through it in this order.

1. Are you on the dashboard built for this machine? Its title names your platform — System Overview — Linux, — macOS (Apple Silicon), — Windows. If it says "Linux / macOS" you're on the portable fallback, which carries every panel for every platform and therefore shows rows your hardware can never fill. You get that when the host has no python3, or when you started docker compose by hand. Re-run the start script — it warns when it falls back:

./scripts/install-macos.sh      # macOS
./scripts/start.sh              # Linux
.\scripts\start.ps1             # Windows

2. Is your install up to date? A fix only reaches ~/.lesysbot/dashboard when you re-run the wizard — lesysbot setup, or lesysbot setup. Then re-run the start script above so the dashboard is regenerated. Without that step you keep running the scripts from whenever you first installed.

3. Which panels?

Digging deeper#

tail -f ~/.lesysbot/logs/lesysbot.log     # plain text: what the program did
tail -f ~/.lesysbot/logs/traces.jsonl     # one JSON line per message you sent

grep -c 'bot[0-9]\{6,\}:' ~/.lesysbot/logs/lesysbot.log

lesysbot chat -v          # DEBUG on screen for one session

logging:
  level: DEBUG

mv ~/.lesysbot/config.yaml ~/.lesysbot/config.yaml.bak
lesysbot setup

rm ~/.lesysbot/tool_state.json

Still stuck? Open an issue at github.com/lesysbot/lesysbot/issues with your lesysbot status output and the last few lines of ~/.lesysbot/logs/lesysbot.log.