Docs/Reference
Troubleshooting
The problems that actually happen, and where to look first.
| Problem | Check |
|---|---|
| Phone won't register | Dashboard → Recent sign-ins and Activity; asterisk -rx "pjsip show endpoints"; on the edge fail2ban-client status kamailio-edge (unban: fail2ban-client unban <ip>) |
| Outside calls fail | User has outside minutes (Billing → User access)? Outbound route matches? asterisk -rx "pjsip show registrations" says Registered? journalctl -u pbx-brain shows outbound ... via trunk? |
| Incoming calls skip someone | They need outside minutes; check journalctl -u pbx-brain | grep skipped |
| Remote phone: no audio | Router forwards UDP 20000–20099 to the edge; the phone uses SRTP (SDES); run ./verify-edge.sh |
| Remote phone: "SDP mismatch" when answering | Set the phone's media encryption to SRTP (SDES) |
| Remote phone never rings | Zoiper killed in the background (phone settings / push); edge config is current (./update-edge.sh) |
| Hang-up doesn't end the call on the other side | Edge config is current; the certificate matches sip.example.com |
| Calls drop after an IP change | systemctl status pbx-edge-ip.timer on the edge; Network page shows "In sync" |
| No emails | Email page → Send test; port 587 or 465 (many ISPs block 25) |
| Can't open admin pages | Use http://<PBX-IP>:8001 from the office network, not the published address |
| Android app: "doesn't support the app yet", or "Not Found" when calling | The PBX is older than the app: run pbx-update. Use the same address as My Phone from outside |
| Android app: "Can't reach …" | Address typed right (https://)? Phone on mobile data can reach your published address? Try it in the phone's browser first. Right after pbx-update, wait 30 seconds |
| Android app: “Sign in with my browser” signs in but doesn't return to the app | Tap Open the My Phone app on that page, or type the code it shows. Check the Server in the app matches the address you signed in at, and run pbx-update (needs the PBX from 14 Oct 2026 or newer) with app 0.7.2 or newer |
| Android app: pairing code "wrong or expired" | Codes work once and for 5 minutes — get a new one in My Phone → App |
| Android app: no notifications | Settings → Notifications → Send a test notification (none = allow notifications in Android); Let it run in the background → Allow; the line under Check now says what the last check found. Texts you send yourself don't notify |
| Android app: the “Connected” notification disappears after a few hours and calls stop ringing | Your phone's battery saver killed the app (Motorola is the worst for this). Update the app (0.7.9 or newer restarts its connection and re-registers by itself, about every 15 minutes). Then Settings → Notifications → Let it run in the background → Allow, and on Motorola also App settings (Motorola battery killer) → Battery → Unrestricted with “Pause app activity if unused” off. Don't swipe the app away from Recents |
| Android app: calls fail | Settings → Calling → Phone login → Get from my PBX → Save. "Remote calling isn't set up" = set the domain under Admin → Network. Otherwise tap Copy details on the call screen for the SIP code |
| Android app: a "1" on the icon that won't go away | Update the app (0.5.1+): the “connected” notification no longer counts |
| Android app: calls to me go to voicemail, the app never rings | Run pbx-update, then in the app Settings → Calling → Phone login → Get from my PBX → Save (the username must end in -app). Check Incoming calls says “Signed in” and allow Let it run in the background |
| Android app: a call says “Not Found” or can't reach the PBX | Run pbx-update; set the remote-access domain under Admin → Network; use Get from my PBX for the phone login |
| Android app: no missed-call notification | Update the app (0.7.1 or newer) and run pbx-update (older apps skipped calls that went to voicemail). Check Check for new things isn't on 15 minutes |
| Android app isn't under Dashboard → Signed in now | Run pbx-update; the app only signs in while Incoming calls is on and says “Signed in” |
| Incoming calls aren't recorded | Run pbx-update (fixed: they were filed under the caller, and calls from outside weren't recorded at all) |
| Single sign-on: “no login here has that username / email” | Sign-on doesn't create accounts: add the login first. Match by username needs the profile scope; by email, the login's notification email must match (and be verified at the provider) |
| Single sign-on: redirect URI error at the provider | Register exactly the Redirect URI shown on Admin → Sign-on; set Panel address from outside to your public address |
| Single sign-on: “issuer” or “expired” errors | Copy the issuer exactly as the provider shows it (trailing slash included); check the PBX clock (timedatectl) |
| Locked out: provider down and the password form is hidden | Open /login?password=1 |
| Edit PIN: “Unlock with PIN” does nothing on some pages | Run pbx-update (fixed: it only worked on the dashboard), then refresh the page |
| My Phone says “Offline – No phone signed in” while the app works | Run pbx-update: the card now counts the app's line (<ext>-app) |
A new user can't use *97 or another star code | Expected: codes are By plan. Add the code to their plan, tick it under Billing → User access → Star codes (no plan), or Allow it for them on Features |
| Store: “Not available” | Store open? Stripe keys set and at least one plan offered and published to Stripe (Billing)? |
| Store: Approve says “No free extensions” or the number is in use | Widen the extension range on Invites; free the number under Routes, or reject the order |
| Store: customer didn't get their login email | Check SMTP on the Email page; Approve shows the username and password on screen when the email fails |
| Android app: “App not installed” / “conflicts with an existing package” | You have an old test build (0.7.2 or older). Uninstall My Phone, install the release from GitHub → Releases, and connect again with Sign in with my browser (one time only) |
| Android app: calls had no audio on 0.7.3 | Fixed in 0.7.5: install the latest release |
| Contact names don't show | Run pbx-update; check the contact's number (any format works). Names show for your own contacts only |
| “Ring my cell too”: the cell never rings | The cell rings for calls to a phone number or ring group that rings you — not for calls dialled straight to your extension. You need outside minutes in your plan, a working outbound route (Routes), and DND off. The cell starts after your delay — if someone answers first, it never rings |
| “Ring my cell too”: answered but it hung up | Press 1 within 12 seconds of answering; anything else hangs up just the cell (that's what stops your cell's voicemail taking the call) |
| Android app signed out by itself | Panel password changed, signed out from My Phone → App, not used for 60 days, or 10 wrong PINs — pair again |
| Inbound SMS doesn't arrive | Webhook URL in voip.ms (re-check the token survived the paste); did_sms_routes has the normalized DID; journalctl -u pbx-api -f for webhook hits |
| Outbound SMS fails | API username is the login email (not account number); journalctl -u pbx-agi -f for msg-route external: lines |
| Incoming calls stop arriving (nothing reaches the PBX), but outgoing calls work | The router forgot the PBX's connection to voip.ms. Run pbx-update (the PBX now checks in with voip.ms every 25 seconds); right now, asterisk -rx "pjsip send register reg-voipms" |
| A desk phone shows busy or doesn't ring after a PBX restart | It hasn't signed in again yet. After pbx-update phones re-register within 5 minutes; to fix it now, power-cycle the phone. Check with asterisk -rx "pjsip show contacts" |
| Faxes: a fax rang through like a normal call (or went to voicemail) | Detect faxes ticked for that number? journalctl -u pbx-agi | grep fax-check says whether the PBX listened and why not. Some senders start silently: raise Listen for |
| Faxes: “didn't come through” / “May be incomplete” | Usually the internet line garbling the fax tones; ask the sender to retry. If it keeps happening, ask voip.ms to enable T.38 for the number |
| Faxes: “built without fax support” on Routes or Faxes | Run pbx-update --with-fax once when the phones are quiet |
| Faxes: “Send a fax” missing or not available | The user needs Fax in their plan (Billing), a number whose route rings them, outside minutes, and faxes left this month. The message under the button says which |
Where the logs live
journalctl -u pbx-brain -u pbx-api -u pbx-agi
asterisk -rvvv
# On the edge:
journalctl -u kamailio -u rtpengine -u fail2ban