Where to look first
If all you know is that the phone doesn’t ring, answer these three questions. Each one checks one step on the way from the app to the PBX and back.journalctl -u pgw. For more detail, set log_level: debug. To see each SIP message, set sip_log: true.
Registration
REGISTER gets 404 Unknown Domain
REGISTER gets 404 Unknown Domain
- Each upstream’s host,
domains, and wildcards. - The domain table of a Kamailio upstream with
use_domain.
404. On a managed upstream with domains, the domain of the To URI must be served too.FixDo one of the following:- Add the domain with
pgw upstream update --id <id> --domains <list>. - Create an upstream with
--hostset to the domain. - Add the domain to Kamailio’s domain table. pgw reads the table every 60 seconds.
- Set the app account’s domain to the user’s domain, so that the Request-URI and the To URI both name it. See Add users at each domain.
The app sends no second REGISTER after 401
The app sends no second REGISTER after 401
log_level: debug, the log shows register challenged with offers and a cause, such as digest credentials, but app_auth is bearer.FixSet the upstream’s --app-auth to a method that the app supports, or to both.A token gets 401 with error="invalid_token", or 403
A token gets 401 with error="invalid_token", or 403
pgw_bearer_verifications_total shows why:invalidis a bad signature, issuer, audience, or expiry, or an unknown key.subject_mismatch(403) is asubthat names another user than the To URI.
log_level: debug, the log shows bearer token refused with the rule that failed.Fix- Compare the token’s
issandaudwith--bearer-issuerand--bearer-audience. - Check the clocks of the issuer and pgw.
- Check that the issuer’s key set holds the signing key.
REGISTER gets 555 Push Notification Service Not Supported
REGISTER gets 555 Push Notification Service Not Supported
pgw app list. For an Android app that sends the Firebase project number, set --fcm-project-number.REGISTER gets 400 Bad Push Parameters
REGISTER gets 400 Bad Push Parameters
Warning: 399 pgw "push subscription host not allowed", the browser’s push subscription isn’t https, or its host isn’t in webpush_hosts.FixCheck the app’s push settings and version. For a browser, add its push service host to webpush_hosts, and restart pgw.REGISTER gets 403 from the PBX
REGISTER gets 403 from the PBX
max_bindings_per_aor plus 1 contacts, plus one for each other phone on the AOR. For the PBX setting, see the page for your PBX: Asterisk or FreeSWITCH.The log shows register ban table full
The log shows register ban table full
pgw ban list. pgw_register_auth_failures_dropped_total counts the refusals that pgw didn’t track.REGISTER gets 500 Server Internal Error with Retry-After: 5
REGISTER gets 500 Server Internal Error with Retry-After: 5
user source unavailable line, err is timeout, refused, authentication, or query. Registered devices stay.A 500 without Retry-After: 5 has another cause: the PBX answered the REGISTER with 503. pgw passes it on as 500, with the PBX’s own Retry-After if the PBX sent one. Check the PBX’s state and load.REGISTER gets 502 Bad Gateway
REGISTER gets 502 Bad Gateway
Warning header names the cause.- With
upstream refused the stored credentials, the app’s password was right. After five refusals in a row, pgw removes the device. With per-user registration, pgw removes every device of the user. - With
upstream answered <status>, the log showsupstream rejected the registration. pgw keeps retrying renewals. - With
upstream did not keep the Path, pgw kept no binding.
REGISTER gets 504 Server Time-out
REGISTER gets 504 Server Time-out
408. Either a firewall drops the traffic, or the upstream’s host is wrong. A UDP upstream on a wrong port also ends here.FixCheck the upstream’s host and port. Check that pgw can reach the PBX through any firewall.REGISTER gets 423 Interval Too Brief once, or the log shows upstream minimum expiry is above max_expires
REGISTER gets 423 Interval Too Brief once, or the log shows upstream minimum expiry is above max_expires
max_expires. pgw then uses the PBX’s minimum, up to one day, until pgw restarts, so the next REGISTER succeeds. In managed mode, the app never sees the 423.FixRun pgw upstream update --id <id> --max-expires <seconds> with at least the PBX’s minimum.REGISTER gets 200 with Expires: 0, and the log shows upstream granted no registration
REGISTER gets 200 with Expires: 0, and the log shows upstream granted no registration
The log shows upstream unreachable, and pgw_upstream_up is 0
The log shows upstream unreachable, and pgw_upstream_up is 0
upstream reachable when the PBX answers again.The log shows upstream did not keep pgw's Path
The log shows upstream did not keep pgw's Path
pgw_upstream_path_missing_total.Fix- Turn on Path support at the PBX. For the setting, see your PBX’s documentation, or Asterisk.
- For a PBX without Path support, delete the upstream with
pgw upstream delete --id <id> --force, and create it again with--contact-strategy masquerade. - To refuse such registrations, run
pgw upstream update --id <id> --strict-path.
The log shows registration not undone at the upstream; the PBX keeps the Contact until it expires
The log shows registration not undone at the upstream; the PBX keeps the Contact until it expires
The log shows binding removed: its device registered another account after a reinstall
The log shows binding removed: its device registered another account after a reinstall
404 until the PBX registration expires.FixNone needed.Incoming calls
To find how a call ended, search the log for its Call-ID. pgw writes onecall ended line for each device that the call rang. The line’s outcome and status say how the call ended for that device.
log_format: json, search for "msg":"call ended".
The call gets 403 Forbidden from pgw
The call gets 403 Forbidden from pgw
invite_source_cidrs.FixRun pgw upstream update --id <id> --invite-source-cidrs <list> with the address. See Allow the PBX to send calls to pgw.The call gets 404 Not Found from pgw
The call gets 404 Not Found from pgw
invite refused with reason no flow token in the request, the PBX sent the call straight to the app’s contact instead of through pgw’s Path.FixCheck pgw binding list, and have the app register again.For a missing flow token, make the PBX keep pgw’s Path header. For a PBX without Path support, use the masquerade contact strategy.The call gets 486 Busy Here, and the log shows call push limit reached
The call gets 486 Busy Here, and the log shows call push limit reached
call_push_rate_per_binding allows, for example in a forwarding loop or from a dialer that retries.FixFix the loop at the PBX. If the device takes that many calls, raise call_push_rate_per_binding or call_push_burst_per_binding.Calls to a user fail at once with 480, and the user's other devices don't ring
Calls to a user fail at once with 480, and the user's other devices don't ring
- In
pgw binding list, find the user’s bindings withflow_alivefalse and noprovider. - Remove each with
pgw binding delete --binding <key>. - Give the PBX room for more contacts. In passthrough mode or with
per_device, allow at leastmax_bindings_per_aorplus 1 contacts, plus one for each other phone on the AOR. With per-user registration, allow one free contact per user. For the PBX setting, see the page for your PBX: Asterisk or FreeSWITCH.
The app registers, but calls never reach pgw
The app registers, but calls never reach pgw
hostname, for example because pgw is behind NAT.Fix- Make the PBX keep pgw’s Path header and the app’s Contact as the app sent it, or use the
masqueradecontact strategy. For the PBX settings, see the page for your PBX: Asterisk or FreeSWITCH. - Behind NAT, set
upstream_hostnameandupstream_portto the public address that forwards toupstream_listen, and have the app register again. Keephostnameas the name in the apps’ certificate check.
The caller keeps hearing ringing after the app answers, and the log shows relay response to upstream failed
The caller keeps hearing ringing after the app answers, and the log shows relay response to upstream failed
pgw upstream update --id <id> --transport tcp, and have the app register again. The PBX must accept TCP.The call connects with no audio
The call connects with no audio
The phone keeps ringing after the caller hangs up
The phone keeps ringing after the caller hangs up
Requests during a call
A request from the app gets 403 Forbidden
A request from the app gets 403 Forbidden
A request from the app gets 481 or 404 from the PBX, and the log shows route dropped
A request from the app gets 481 or 404 from the PBX, and the log shows route dropped
invite_source_cidrs, such as its public address behind NAT or another cluster node. pgw sends the request to the upstream’s address instead. There, the PBX can’t match the request to the call.FixAdd each address that the log names in host to --invite-source-cidrs. pgw must be able to reach them.A request from the PBX gets 480, and the log shows app flow closed; request not relayed
A request from the PBX gets 480, and the log shows app flow closed; request not relayed
app_idle_timeout.A request from the app gets 480 with sips requires a TLS upstream
A request from the app gets 480 with sips requires a TLS upstream
sips: URI, which requires TLS on every hop. pgw reaches PBXs over UDP or TCP only. The log shows sips request refused; the upstream has no TLS.FixConfigure the app to use sip: URIs with TLS transport. The app’s connection to pgw stays encrypted.A request gets 500 from pgw, and the log shows relay request failed or relay to app failed
A request gets 500 from pgw, and the log shows relay request failed or relay to app failed
503, or pgw couldn’t reach it.FixCheck the other side’s load. Check that pgw can reach it.A request gets no response, and the log shows request timed out
A request gets no response, and the log shows request timed out
408 only to INVITE, so the sender’s own transaction times out.FixCheck that the other side is reachable and answers the method.Pushes
No push arrives
No push arrives
pgw binding test-push --binding <key> with a key from pgw binding list.APNs returns 400 BadDeviceToken
APNs returns 400 BadDeviceToken
sandbox for builds from Xcode, and production for TestFlight and App Store builds.pgw binding list shows a dead_reason
pgw binding list shows a dead_reason
dead binding not removed. pgw sends the binding no pushes.FixNone needed. pgw deletes the binding at the next renewal scan in managed mode, or when its registration expires.An Android app gets no push after it was closed
An Android app gets no push after it was closed
A push event shows push: skipped
A push event shows push: skipped
A web push event shows push service host not allowed
A web push event shows push service host not allowed
webpush_hosts.FixAdd the host to webpush_hosts, and restart pgw.TLS and app connections
The app doesn't connect
The app doesn't connect
The log shows app TLS handshake failed
The log shows app TLS handshake failed
err names the cause: bad certificate when the app rejected the certificate, or first record does not look like a TLS handshake when the app used plain TCP.FixCheck that the certificate covers hostname, and that the app uses TLS.The app's REGISTER gets no answer
The app's REGISTER gets no answer
New app connections fail at a steady number
New app connections fail at a steady number
open-file limit below app_max_connections; raise LimitNOFILE or lower app_max_connections.FixRaise the open-file limit, or lower app_max_connections.Startup
pgw exits at startup
pgw exits at startup
pgw: , and exits with status 1.The log shows upstream uses TLS, which pgw doesn't support
The log shows upstream uses TLS, which pgw doesn't support
503.FixRun pgw upstream update --id <id> --transport tcp, or udp if the PBX doesn’t accept TCP.The log shows upstream has a DNS name and no invite_source_cidrs; pgw refuses its calls
The log shows upstream has a DNS name and no invite_source_cidrs; pgw refuses its calls
403.FixRun pgw upstream update --id <id> --invite-source-cidrs <list> with the PBX’s addresses.Configuration changes
An upstream change fails with 400 and is a wildcard on a public suffix
An upstream change fails with 400 and is a wildcard on a public suffix
*.lan, or a public suffix, such as *.co.uk.FixList a name under the suffix, such as *.example.com. pgw checks every domain on any change, so remove the wildcard before you change the upstream.An upstream change fails with 409 and is already served by another upstream
An upstream change fails with 409 and is already served by another upstream
- Another of your upstreams has the name.
- Another tenant has a name that yours equals, falls under, or covers. The other tenant’s name can be an upstream’s host, a domain, a wildcard, or a domain in a Kamailio domain table.
The log shows another tenant's kamailio domains hold the domain; pgw's configuration keeps it
The log shows another tenant's kamailio domains hold the domain; pgw's configuration keeps it
upstream_id already lists. REGISTERs still go to that upstream.FixRemove the domain from the Kamailio table, or from the upstream if the other tenant should serve it.A domain change fails with 409 and every user of an upstream with domains needs a domain that it serves
A domain change fails with 409 and every user of an upstream with domains needs a domain that it serves
- To add the first domains, give each user a domain in the same
pgw config sync, with--prune. - To remove a domain, delete its users first.
pgw upstream create --user-source kamailio fails with connect, domain table, or subscriber table
pgw upstream create --user-source kamailio fails with connect, domain table, or subscriber table
--kamailio- flags and the database user’s grants. See Create the database user.