● Ship · When something is wrong
Troubleshooting
symptoms, causes, checks.
Start with Status in the console: each check says what is wrong. The server log never contains keys or e-mail addresses.
01Where to look
journalctl -u answerbell -f # the server log (systemd)
curl https://<your URL>/healthz # {"ok":true}On Windows run curl in PowerShell (curl.exe) or Git Bash; the log commands run on the Linux server.
02Symptoms
| Symptom | Likely cause | Check |
|---|---|---|
| The number rings but nobody answers | number not imported in ElevenLabs or no agent assigned | ElevenLabs → Phone numbers: the number exists and has the client's agent (Telnyx step 3) |
| Busy tone or "number not in service" | the Telnyx number is not on the SIP connection, or not activated | Telnyx → Numbers → Connection; regulatory status of the number |
| The assistant asks every caller for their number before booking | ElevenLabs did not receive the calling number over SIP (it is only documented with an X-CALLER-ID header) | Nothing is broken: the booking uses the number the caller says. The call log still shows the number when ElevenLabs records it |
| The agent answers but cannot check times | the tools cannot reach this server | Voice agent → Public URL is https and reachable; curl -X POST https://<url>/tools/x/business_info answers 404 JSON (not a timeout) |
| Tool requests answer 401 in the log | the agent has an old tool secret (after a key change or restore) | press Update agent on the client |
| Client shows out of date | edited without an ElevenLabs key, or the update failed | press Update agent; the error is on the client page |
| Create agent fails with ElevenLabs 401 | wrong key or missing Agents permission | Integrations → ElevenLabs → Test connection |
| Create agent fails with ElevenLabs 422 | invalid model id or voice id in Voice agent | clear the voice id or pick a model ElevenLabs lists |
| No calls on the Calls page | sync off, key missing, or calls not finished yet | Status → Calls are fetched; Fetch new calls now |
| No booking e-mails | Resend key, sender domain not verified, or e-mails switched off | Status → E-mail can be sent shows the last error |
| Subscriptions stay none after payment | webhook missing or wrong signing secret | Stripe → Webhooks → recent deliveries; 400 = wrong secret |
| "Read-only demo" on every change | DEMO_MODE=1 or ADMIN_DEMO_PASSWORD is set | remove both on your own server |
| Saved keys "cannot be decrypted" | ADMIN_SECRET_KEY changed | restore the old key, or enter the keys again and update every agent |
pnpm install fails on better-sqlite3 | no prebuilt binary and no build tools | build-essential python3 (Linux), Xcode Command Line Tools (macOS), Visual Studio Build Tools (Windows) |
| A change in the code or an update has no effect | dist/ still holds the old compiled code | run pnpm build, then restart the service |
The service does not start and the log names dist/src/index.js | pnpm build was never run in that folder | pnpm install && pnpm build in /opt/answerbell |
| The agent does not recognise returning callers, or calls have no mood and outcome | the agent was made before the version that added the tool or the labels | Update N agents on the Clients page |
Calendar link fails with redirect_uri_mismatch | the redirect URI in your Google or Microsoft app differs from the public URL | set exactly https://<public URL>/oauth/callback (Calendars) |
| Status warns Linked calendars are in sync | a linked calendar could not be read (for example the business removed the access) | open the client's Calendar tab and link the calendar again |
| Status warns Webhook deliveries succeed | your endpoint answered non-2xx or slower than 10 seconds | Webhooks → Recent deliveries shows the answer (Delivery) |
| The transfer does not ring | the business is closed (transfers only while open), or your trunk refuses SIP REFER | test during opening hours; switch the transfer to conference (Transfer) |
| Portal sign-in e-mail never arrives | the address is not on the client's Portal tab, or e-mail is not set up | Portal tab; Status → E-mail can be sent |
| Port already in use | another service on 8080 | set PORT in .env |
03Lost passwords
A manager's or viewer's password: an owner removes the member under Team and adds them again (a new password is shown once). The only owner's password: stop the server, move data/admin.sqlite aside (settings and keys are lost with it), start again and use the new setup code from the log; then enter the settings and keys again.