Troubleshooting

Start here

flowly doctor          # diagnose
flowly doctor --fix    # diagnose, and auto-repair the fixable issues

doctor walks ~20 checks and prints each as ok, warn, or error, with a hint for anything that needs attention. The fixable ones (config formatting, workspace scaffolding, etc.) are repaired in place when you pass --fix.

What it checks

Common issues

"No provider key" / the agent won't answer. You haven't configured an LLM provider. Run flowly setup → pick a provider → paste a key (or sign in to Flowly Cloud). flowly doctor flags this.

Config won't load / duplicate keys. config.json keys are camelCase. A classic foot-gun is having both apiKey and api_key — Flowly converts both to the same internal key and the last one wins. flowly doctor --fix reports and helps clean these.

Gateway changes don't take effect. Channel tokens, plugin enable/disable, and similar need a gateway bounce: flowly restart. (Provider/model swaps hot-reload via slash commands and don't need a restart.)

"flowly: command not found" after install. The launcher is on PATH in your shell profile, but the shell you ran the installer from hasn't re-read it — most common right after a curl … | bash install, which runs in a child shell. Activate it in the current shell with the line the installer prints:

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

Or just open a new terminal — the install script already updated your shell profile, so fresh shells pick it up.

The bot doesn't start on boot (Linux). systemd user services need linger enabled to run without an active login: loginctl enable-linger $USER. flowly doctor checks this.

Port already in use / "gateway already running". Something is already listening on the gateway port (default 18790) — usually a foreground flowly gateway or a duplicate of the service. flowly service status shows a diagnostic and warns when a gateway is running outside the service. Stop the stray process (or flowly service stop) before starting again. Flowly never force-kills a gateway it didn't start — including the one Flowly Desktop manages — so two installs won't fight over the port silently.

Windows-specific

Do I need an administrator shell for the service? No. flowly service install tries Task Scheduler first and, if that's denied, automatically falls back to a Startup-folder launcher that runs the gateway at logon — no elevation required either way.

A ~lowly-ai folder appears / "flowly" isn't recognized (packaged pip install). Specific to a pip install --user flowly-ai install: an interrupted pip upgrade — or one that ran while flowly.exe was locked — can leave a partial ~-prefixed folder in your user site-packages. flowly update now relaunches itself on Windows to avoid the locked-exe case, but if you land in a half-broken state, delete the leftover and reinstall:

$sp = python -m site --user-site
Remove-Item (Join-Path $sp "~lowly*") -Recurse -Force -ErrorAction SilentlyContinue
pip install --user --force-reinstall flowly-ai

A git-checkout install — the default from the install script — never touches site-packages, so this can't happen to it; re-run the installer or flowly update to repair one.

A UnicodeEncodeError / cp1252 traceback on Windows. Flowly's ✦ logo (and other Unicode) can't encode on a non-UTF-8 Windows console — a redirected/piped stream, or certain locales. Fixed in current releases: every flowly command now forces UTF-8 output (not just the gateway). If you hit it on an older build, flowly update to the latest.

Channel silent / not receiving. Confirm the channel is enabled in config and that access control (allowFrom / pairing) permits the sender. See the channel's own page under Channels.

Still stuck?

• Check the logs: flowly service logs (service mode) or the terminal running flowly gateway.
• Verify your install mode and version: flowly --version, then flowly update --check.
• Inspect what's on disk: see the file layout.