Troubleshooting

The real questions, with the actual answers.

Page	Symptom
Phone can't reach Pluma	Pluma's running on your Mac/PC but your phone gets a connection error or never loads.
Voice sounds garbled	TTS plays something but it's the wrong voice, wrong words, mid-sentence cutoffs, or audible repetition.
Config won't parse	Pluma exits right after start with a TOML error in the log.
Model downloads fail	HF browser starts a job that errors immediately or stalls forever.

Not here? Open a bug report with the version + OS + browser + what you tried. The template prompts for everything I'll ask for first anyway.

General debugging recipe

1. Check the server log. Pluma writes to stderr; when started via dev-watch.sh that lands at /tmp/pluma.log. tail -50 shows the recent error context.
2. Check the browser console. F12 → Console. Any [tts] / [chat] / [image] lines from Pluma + any red exceptions from the SPA.
3. Check /api/health in your browser. Returns {ok: true, upstream: "..."}. If ok: false, the upstream LLM isn't reachable — see Connections setup.
4. Check lsof (macOS / Linux) or netstat -ano (Windows) for the listen port. Tells you whether Pluma is actually bound where you think.

When to delete state

Reset	What you lose
~/.config/pluma/config.toml	Custom settings; defaults regenerate on next start (with comments).
~/.config/pluma/conversations/*.json	Chat history.
~/.config/pluma/credentials.json	Enrolled passkeys; you'll re-pair on the next request.
~/.config/pluma/tsnet/	Tailscale node state; re-auth on next enable.
Whole data directory	Everything. Useful to re-test the first-run flow on a fresh slate.

Encrypted files (conversations, credentials, tokens) are useless without the keyring key. Back up the key with pluma -export-storage-key before nuking the data dir.