ChatPilot
Troubleshooting and FAQ

Something isn't working

The usual problems, from a panel that won't open to an unlinked WhatsApp, and how to fix each one.

Find your problem below. Most of them are fixed in the panel; a few need a terminal. If yours isn't here, or the fix doesn't help, report it.

First: is ChatPilot running?

uv run chatpilot service status

If it isn't running, start it with uv run chatpilot service restart. To see what it is doing, or why it stopped:

uv run chatpilot service logs -f

The log files themselves are listed under Where ChatPilot keeps things.

"chatpilot is already running" means a second copy was started while the service runs. Only one may run at a time. Use the service, or stop it first (uv run chatpilot service uninstall) if you want to run it in a terminal.

The panel won't open

  • Open it with uv run chatpilot open, or with the link that /admin gives you in your Telegram control bot. The link carries the panel's key: a plain 127.0.0.1:47821 without it can't load your inbox.
  • The panel is on your own computer. From another device, use the phone link (see On your phone), not the computer's address.
  • On a server, reach it as described in A server that runs all the time.

I lost the panel's password or authenticator

If you set up sign-in with a password, run this on the computer ChatPilot runs on:

uv run chatpilot panel-login reset

It removes the password and signs everyone out. Then open the link from uv run chatpilot open and set sign-in up again.

The control bot doesn't answer me

  • The bot only answers its owner. Check that owner_id under control: in config.yaml is your own Telegram user id (ask @userinfobot), then restart ChatPilot.
  • Check that the bot's token is stored: uv run chatpilot secret list should show control_bot_token as set. See First start.

Messages from a chat don't show up

  • Every chat starts Off. Switch it on in Settings → Which chats ChatPilot may read: see Choose which chats ChatPilot may read.
  • A chat set to Saved, no AI shows its messages, but gets no sorting, drafts or summaries.
  • Check the app's card under Settings: it should say linked or connected.

WhatsApp says "unlinked"

The link was ended, usually on the phone (Linked devices), or WhatsApp ended it after the phone was offline for a long time. Open Settings → WhatsApp, press New code and scan it again: see Link WhatsApp. Your chats and their settings stay in ChatPilot.

The code expires after about a minute. When the card says The code expired., press New code.

Telegram stopped receiving

If you ended ChatPilot's session in Telegram (Settings → Devices), open Settings → Telegram and press Log in again. See Link Telegram.

A mailbox stopped working

  • A Google mailbox shows Sign in again when its sign-in no longer works. Press it.
  • A mailbox with a password: the password may have changed, or the provider wants an app password (iCloud always does). See Add a mailbox.

No drafts, no sorting, no summaries

These need the AI. Open Settings → AI and press Test connection:

  • Claude Code, Codex CLI, Gemini CLI: the program must be signed in on the computer ChatPilot runs on. Sign in here does that from the panel.
  • An API: check the key, and that your account with that service has credit.
  • Only the AI on this computer chats wait while the local model isn't running; they never go to the main AI instead. Start Ollama or LM Studio and they are done then.

See Choose the AI.

A connected system says "Sign in again"

Its sign-in expired or was withdrawn. Open Settings → Connected systems and press Sign in again on that system; a system with a key needs its key again. See Connect a system.

Auto-answer didn't answer

That is usually on purpose. The small line in the chat says why it held its reply back for you: for example it wasn't sure enough for the chat's level, a figure in its reply wasn't found in the chat, the chat reached its Max per day, or you wrote yourself a moment ago. Also check that it isn't stopped everywhere: Automation → Rules & auto-answer → Autonomy. See Switch on auto-answer and See what ChatPilot did.

A banner says settings.json has an error

Someone edited the settings file by hand and it has a mistake. Nothing was taken from it: your settings stay as they were. Press Fix it to open the file in the panel and correct the line it names, or undo the hand edit.

Updates

Couldn't check, can't update itself and a Restart button at the top are explained in Updates.

Still stuck?

Use Settings → Help: report a problem. Add a screenshot if it helps (you can blur names and messages first) and the diagnostics. See Report a problem.

Checked against ChatPilot 0.1.0b1. Report a problem with this page