Troubleshooting
What to do when something goes wrong with install and keys, Beeper, the Telegram bot, briefs, the dashboard or
the phone line. You marks a step only you can do, not an AI helping you. Commands that start with /, like
/resume, go to the bot in Telegram; the full list is in Telegram commands.
Doctor is Pepper's health check, and it's the first thing to run. It checks every connection without changing anything in them and spends none of your Anthropic credit. It does open Pepper's database, and it renews a saved sign-in that is close to expiring.
npm run doctorEvery line should say ok, or off for a part you haven't turned on. A FAIL line names the check and the
problem. Pepper's log is data/pepper.log, with errors in data/pepper.err.log.
After changing .env, the file that holds Pepper's keys and settings, restart Pepper:
launchctl kickstart -k gui/$(id -u)/com.pepper.agent| Symptom | Cause | Fix |
|---|---|---|
Missing required env var TELEGRAM_BOT_TOKEN (see .env.example), or another name | That line of .env is empty, or .env is not in the Pepper folder | Fill it in from Install Pepper, steps 5 to 7 |
Doctor: anthropic FAIL | The API key is wrong, revoked or out of credit | You: check the key at platform.claude.com. A backup key in ANTHROPIC_API_KEY_BACKUP is used when the first runs out |
Doctor: files or memory FAIL, readable by others | Other users on the Mac could read Pepper's files | Run chmod 600 on the file the line names, or chmod 700 on the folder |
the database is schema v…, this code knows v… | A newer copy of Pepper wrote the database | Update the code (git pull, npm install) and restart |
Doctor: search FAIL | The search index is out of step | npm run backup, then sqlite3 data/pepper.sqlite "INSERT INTO messages_fts(messages_fts) VALUES('rebuild');" (use your data folder if it isn't data/) |
Doctor: speech says off, or voice notes come back Couldn't transcribe | Local speech-to-text is not installed | brew install uv ffmpeg, then uv tool install parakeet-mlx |
Doctor: voice FAIL | Pepper's voice is on but not set up | brew install uv ffmpeg, then scripts/setup-tts.sh. Until then the Mac's built-in voice stands in |
Doctor: semantic FAIL | Semantic search is on but not set up | brew install uv, then scripts/setup-embed.sh. Until then search uses keywords |
Doctor: ram FAIL | The Mac is short of memory | Quit other apps, or turn off voice or semantic search |
Doctor: host FAIL | The Mac sleeps, or stays off after a power cut | You: see host setup |
The one-line install says could not clone | The repository is private, or the Mac is offline | Unpack the copy you were given and run scripts/bootstrap.sh from inside it |
npm run setup says run this in a terminal | It was started from a script or an editor, not Terminal | Run npm run setup in Terminal; it reads keys without showing them |
| Setup stopped partway | One part failed three times | What worked is already in .env. Fix the part it named, then npm run setup <part> |
Doctor: node FAIL | Pepper is using an older Node version | nvm install 24 && nvm alias default 24, then open a new Terminal tab |
TELEGRAM_API_ROOT is for tests only | That line is in .env | Delete it |
BEEPER_BASE_URL must point at this Mac | Beeper's address points elsewhere | Use http://localhost:23373 |
Pepper gets the chats you connect through Beeper Desktop, using a read-only token.
| Symptom | Cause | Fix |
|---|---|---|
Doctor: sources FAIL | BEEPER_ACCESS_TOKEN is empty | Make the token (install step 4) and add it to .env |
Doctor: beeper FAIL, timed out or refused | Beeper Desktop isn't running | You: open Beeper Desktop and have it start at login |
Doctor: beeper FAIL, reachable, but no accounts connected | No chat apps added in Beeper | You: add your chat apps in Beeper Desktop |
Doctor: beeper FAIL, not connected: whatsapp=… | One chat app has signed out or lost its connection | You: reconnect that app in Beeper Desktop |
Doctor: beeper-token FAIL, expires in N days, expired or expired or revoked | The token was set to expire (Beeper's dialog defaults to 30 days), has expired, or was removed in Beeper | You: make a new read-only token with Expires In: Never (install step 4), put it in .env, restart |
Doctor: beeper-token FAIL, can send and change chats, or setup rejects a token for this | The token was made with Allow sensitive actions ON | You: delete it in Beeper and make one with sensitive actions OFF. Pepper doesn't check again while it runs, so use a read-only token from the start |
Doctor: beeper-token FAIL, read-only isn't confirmed | This version of Beeper Desktop can't say what the token may do, and the read-only token is what keeps Pepper from sending | Update Beeper Desktop, then npm run doctor |
/status shows beeper as needs you or broken, or the brief says no successful sync since … | Beeper is closed or the token was revoked | Open Beeper, or make a new read-only token, then /sync |
| A chat never appears | That app isn't in Beeper, or the chat is ignored | Check Beeper, then /chats and /normal <chat_id>. /chats lists only the 25 most recently active chats |
| Symptom | Cause | Fix |
|---|---|---|
| The bot never answers | Wrong TELEGRAM_OWNER_ID, Pepper isn't running, or you wrote in a group | npm run setup telegram learns your id from your first message (or get it from @userinfobot), then restart. Use the bot's private chat |
Setup: Another Pepper is already reading this bot (409), or data/pepper.err.log shows 409: Conflict: terminated by other getUpdates request | Another Pepper is using the same bot, often the old Mac after a move | You: stop the other one (Moving to another Mac), then try again |
npm run digest -- --send fails, but the token is right | Telegram bots can't start a chat | You: open the bot and send /start |
Doctor: telegram FAIL, Unauthorized | The bot token is wrong or revoked | New token from @BotFather, then restart |
Paused (/resume to continue). | Pepper is halted | /resume |
Spend cap reached … | The daily or monthly budget is used up | Wait. Briefs have money set aside and still run |
Couldn't transcribe that voice note (…) | The reason is in the brackets: speech tools missing, the recording empty or too big, or OpenAI refused it | Install speech-to-text if it's missing (the speech row under Install and keys); otherwise try a shorter recording |
No longer pending. after a tap | That button was used or expired | Reply to the newest brief in words |
| A command gets no reply | Pepper doesn't know it | See Telegram commands |
Something failed: … | A model or network error | Try again. If it repeats, run doctor |
| Symptom | Cause | Fix |
|---|---|---|
| No brief at all | Pepper isn't running | launchctl list | grep com.pepper.agent. If it's missing, run launchd/install.sh |
launchd/install.sh: Bootstrap failed: 5: Input/output error | The old Pepper was still shutting down when the new one was started (fixed in the installer) | Run launchd/install.sh again |
Doctor: pepper FAIL, HALTED | /halt was sent | /resume |
| Briefs arrive at the wrong hour | The timezone is wrong | Set PEPPER_TZ (for example Europe/London) and restart |
| A brief is missing after the Mac was off | Pepper came back more than 90 minutes after the brief was due | /brief for one now. Stop the Mac sleeping: host setup |
morning brief failed: … | Building or sending the brief failed | Read the reason, fix it, then /brief |
Doctor: stale spend reservation(s) | Pepper stopped mid-call | Restart Pepper |
Every brief says Nothing is waiting on you. | Often normal: nothing in your chats needs a reply from you. Otherwise no messages are coming in, or the chats are muted | /status, then /chats |
The dashboard is Pepper's set of web pages, which you open over Tailscale, a private network between your own devices.
| Symptom | Cause | Fix |
|---|---|---|
Doctor: dashboard says off | PEPPER_DASH_USERS is empty | Add your Tailscale login, then restart |
Misdirected (421) | PEPPER_DASH_ORIGIN is unset or wrong | Set it to the exact https://…ts.net address |
Forbidden (403) | Your login isn't in PEPPER_DASH_USERS, or you skipped Tailscale Serve | Add the login and open the ts.net address |
| The page doesn't load | Serve isn't running, or the device isn't on your Tailscale network | tailscale serve --bg 7777. You: sign the device in to Tailscale |
Session required | Pepper restarted, and that ended your session | Reload the page |
Buttons say Paused (/resume in Telegram). | Pepper is halted | /resume |
You can talk to Pepper by phone, and the phone guides have troubleshooting tables of their own:
- Bridge, adb, FreeSWITCH and audio problems: Android bridge troubleshooting.
- Passphrase, caller and call problems: Talking to Pepper by phone.
The phone check fails when the phone line is on but your number or passphrase is missing. Set the passphrase
with npm run phone -- passphrase.
Run doctor and /status, and read the end of pepper.err.log. Report a security problem privately, by email to
hello@heypepper.ai with "security" in the subject.
Google Calendar
Not built yet. When it is, Pepper will read your calendar so the Schedule tab shows your meetings next to your deadlines, and the morning brief shows what your day looks like. It will only read. It…
Frequently asked questions
No. Pepper never writes to the chats it reads. Pepper reaches your chats through Beeper Desktop, and the token that gives it access is created with "Allow sensitive actions" off, so Beeper itself…