Skip to main content
Each entry is named for what you see: a SIP status code, a log line, or a command’s error. Find yours in the section for its area, and open it.

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. A call to an app that was still connected has no event in the push log, because pgw sent no push. If all three answers are yes, the push service took the push. The problem is most likely on the device or in the app. See Handle a call push. To read the log, run journalctl -u pgw. For more detail, set log_level: debug. To see each SIP message, set sip_log: true.

Registration

CauseNo upstream serves the host in the Request-URI. pgw matches the host by name against:
  • Each upstream’s host, domains, and wildcards.
  • The domain table of a Kamailio upstream with use_domain.
A domain that resolves to the PBX’s address still gets 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 --host set 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.
CauseThe app gets the same 401 for three different causes. To tell them apart, check which reason of pgw_register_auth_failures_total grows:Fix
  • Check the user in pgw user list --upstream <id>. Set the password with pgw user set --id <user-id> --password.
  • On an upstream with domains, set the app’s account domain to the user’s domain, or create the user there with pgw user create --domain.
  • On a Kamailio upstream, if only subscribers with an ha1 fail, the ha1 values use another realm. Create the upstream again with --realm set to Kamailio’s realm. See Match Kamailio’s realm.
Causepgw offered only methods that the app doesn’t support. For example, it offered Bearer to an app that signs in with a password.With 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.
Causepgw refused the token. pgw_bearer_verifications_total shows why:
  • invalid is a bad signature, issuer, audience, or expiry, or an unknown key.
  • subject_mismatch (403) is a sub that names another user than the To URI.
With log_level: debug, the log shows bearer token refused with the rule that failed.Fix
  • Compare the token’s iss and aud with --bearer-issuer and --bearer-audience.
  • Check the clocks of the issuer and pgw.
  • Check that the issuer’s key set holds the signing key.
CauseNo App matches the app’s push parameters. On iOS, that is the bundle ID. On Android, it is the Firebase project ID or number. For a browser, the tenant has no web App.FixCompare the app’s push parameters with pgw app list. For an Android app that sends the Firebase project number, set --fcm-project-number.
CauseThe Contact’s push parameters don’t parse.If the response has 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.
CauseThe password is wrong, or the AOR reached the PBX’s contact limit.FixCheck the password in the app. For a full AOR, give the AOR room for at least 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.
In the register source banned line, banned_source names the banned address or /64, and aor is the last refused account. Devices behind the same NAT share the ban.
Causepgw tracks wrong passwords from 65,536 source addresses at most. Until bans end and free the table, pgw doesn’t count or ban new addresses.FixBlock the attacking networks at the firewall. To see the bans, run pgw ban list. pgw_register_auth_failures_dropped_total counts the refusals that pgw didn’t track.
In the 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.
The Warning header names the cause.The first two warnings appear in managed mode.
  • 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 shows upstream rejected the registration. pgw keeps retrying renewals.
  • With upstream did not keep the Path, pgw kept no binding.
CauseThe PBX didn’t answer within 20 seconds, or it answered 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.
CauseThe PBX’s minimum registration time is above the upstream’s 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.
CauseThe PBX accepted the REGISTER but kept the contact for 0 seconds.FixCheck the PBX’s limits on registration time and on contacts per AOR.
CauseThe upstream missed 3 OPTIONS in a row. The PBX is down, a firewall drops pgw’s traffic, or the host or port is wrong. Registrations and calls through the upstream fail.FixCheck that the PBX listens on the upstream’s port and that the firewall lets pgw reach it. pgw logs upstream reachable when the PBX answers again.
CauseThe PBX doesn’t support Path or has it off, so it would send calls straight to the app. pgw counts each case in 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.
Causepgw refused a registration that the PBX accepted. pgw then sent a REGISTER to remove it, and the PBX challenged that REGISTER. The PBX can send calls to the contact until it expires.FixNone needed. To remove the contact sooner, delete it on the PBX.
CauseAn iPhone app was reinstalled and signed in to another account with the same VoIP token. pgw removed the first account’s binding. pgw answers the PBX’s calls to that binding with 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 one call ended line for each device that the call rang. The line’s outcome and status say how the call ended for that device.
With log_format: json, search for "msg":"call ended".
CauseThe PBX sent the call from an address outside the upstream’s 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.
Causepgw has no binding for the called contact, for example after the app unregistered.If the log shows 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.
CauseThe PBX sent the device more calls than 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.
CauseThe PBX’s only contact for the user belongs to a device that pgw can’t wake, because it has no push and isn’t connected. In managed mode, pgw removes such a device within seconds of its connection closing. In passthrough mode, the device stays until its registration expires.Fix
  1. In pgw binding list, find the user’s bindings with flow_alive false and no provider.
  2. Remove each with pgw binding delete --binding <key>.
  3. Give the PBX room for more contacts. In passthrough mode or with per_device, allow at least max_bindings_per_aor plus 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.
Causepgw pushed, but the app didn’t register again within hold_seconds, 30 by default. The Reason is device did not wake.FixCheck that the push arrives, and that the app registers when it arrives. For slow devices, raise hold_seconds.
CauseThe PBX ignores the Path, rewrites the Contact, or can’t reach 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 masquerade contact strategy. For the PBX settings, see the page for your PBX: Asterisk or FreeSWITCH.
  • Behind NAT, set upstream_hostname and upstream_port to the public address that forwards to upstream_listen, and have the app register again. Keep hostname as the name in the apps’ certificate check.
CauseThe network dropped the answer on its way to the PBX. Over UDP, a large answer travels as several IP fragments, and some networks drop fragments.FixRun pgw upstream update --id <id> --transport tcp, and have the app register again. The PBX must accept TCP.
CauseThe PBX can’t reach the phone for RTP.FixMake the PBX send media to the address that it receives media from, and keep media flowing through the PBX. For the settings, see your PBX’s documentation, or Asterisk.
CauseThe app didn’t act on the missed-call push.FixOn iOS, turn on remote pushes in the app. The missed-call push goes to the remote token.

Requests during a call

CauseThe app sent the request on another connection than the one that it registered on, for example after a network change.FixHave the app register again on every network change.
CauseThe PBX record-routes an address outside the upstream’s 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.
CauseThe app closed its connection during the call, for example because the device slept. pgw reaches an app only over the connection that the app opened.FixKeep the app connected during calls, with keepalives more often than app_idle_timeout.
CauseThe app used a 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.
CauseThe other side answered 503, or pgw couldn’t reach it.FixCheck the other side’s load. Check that pgw can reach it.
CauseThe other side didn’t answer within 32 seconds. pgw answers 408 only to INVITE, so the sender’s own transaction times out.FixCheck that the other side is reachable and answers the method.

Pushes

CauseThe push service refused the push, or the credentials don’t match the app build.FixCheck the status and error in the push log. To test one device, run pgw binding test-push --binding <key> with a key from pgw binding list.
CauseThe App’s APNs environment doesn’t match the build.FixUse sandbox for builds from Xcode, and production for TestFlight and App Store builds.
CauseThe push service reported the token invalid, and pgw couldn’t delete the binding, usually because the database failed. The log shows 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.
CauseThe app was force-stopped.FixOpen the app once. Close it by swiping it away, not with Force stop.
CauseOn iOS, the app registered no remote token, so pgw skips missed-call and refresh pushes. A web app gets only call and test pushes.FixOn iOS, turn on remote pushes in the app.
CauseThe subscription’s host isn’t in webpush_hosts.FixAdd the host to webpush_hosts, and restart pgw.

TLS and app connections

CauseThe app rejected pgw’s certificate, or port 5061 is blocked.FixInstall a TLS certificate from a public certificate authority, and open 5061/tcp.
CauseThe line’s 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.
CauseThe app sent it to port 5060. pgw takes REGISTER only on the app listener.FixSet the app’s transport to TLS and its port to 5061.
Causepgw reached its open-file limit. At startup, it logged 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 writes the reason to standard error after pgw: , and exits with status 1.
Causepgw doesn’t connect to PBXs over TLS. pgw answers the upstream’s REGISTERs, and the apps’ requests toward the upstream, with 503.FixRun pgw upstream update --id <id> --transport tcp, or udp if the PBX doesn’t accept TCP.
CauseNo prefix allows the PBX’s addresses, so pgw answers its calls with 403.FixRun pgw upstream update --id <id> --invite-source-cidrs <list> with the PBX’s addresses.

Configuration changes

CauseA wildcard covers a single label, such as *.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.
CauseOne of the following is true:
  • 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.
FixRemove the name from your other upstream, or use another name. The tenant that listed a name first keeps it.
CauseAnother tenant’s Kamailio domain table gained a domain that the upstream in 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.
CauseThe change would leave a managed user at a domain that the upstream doesn’t serve. Either you added the first domains to an upstream whose users have none, or you removed a domain that users still have.Fix
  • 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.
See Add users at each domain.
Causepgw couldn’t connect to the database, or couldn’t read the named table.FixCheck the --kamailio- flags and the database user’s grants. See Create the database user.

Next steps

SIP responses

Look up a status code that this page doesn’t list.

Logs

Follow one device or call through the log by its fields.