First locate the failed leg
Record the dialed destination, originating extension, time and observed hangup cause. Confirm that the dialplan selected the intended gateway and whether a carrier-facing INVITE was sent. A local GATEWAY_DOWN before that INVITE points to a different boundary from a 403 or 503 returned by the carrier. A hangup cause alone can hide the original SIP response; retain both when one exists.
Compare a known permitted call through the same gateway. Keep an explicit restriction test after any route change so a repair does not widen calling permissions.
Read the two gateway state fields
Use sofia status gateway <name> on the relevant FreeSWITCH instance. Inspect both State and Status. REGED describes a current registration on a gateway configured to register. NOREG is expected when registration is disabled, including many IP-authenticated trunks; it is not itself evidence of failure. FAILED, FAIL_WAIT, EXPIRED or TIMEOUT call for a registration-path investigation. The UP/DOWN summary can also reflect OPTIONS reachability.
Check that the gateway is enabled on the intended running Sofia profile. A gateway with NOREG / UP may still fail a call because of routing, identity or an upstream decision. Do not turn on registration solely to make the state read REGED.
sofia status
sofia status gateway <name>
sofia status profile <profile>If registration is required, follow its exchange
For a registering carrier, compare the configured proxy, realm and authentication identity with the carrier contract. Scope SIP tracing to the affected profile during a short test window, inspect REGISTER challenges and responses, then turn tracing off. A timeout requires network, DNS or far-end reachability evidence; a rejected challenge requires identity and policy evidence. Avoid changing credentials and firewall rules together.
If the carrier uses IP authentication, confirm the permitted source address and the gateway ping target under that carrier’s documentation. Registration failure logic does not apply to a gateway deliberately set not to register.
If an INVITE leaves, follow the response
Capture the actual SIP final response on the outbound leg. A provider 403 may concern caller identity, permissions or authentication; a 404 can concern number format or routing; a 503 can describe upstream unavailability. FreeSWITCH maps SIP responses into hangup causes, so the mapped cause is a clue rather than a complete explanation. Correlate it with the dial string, selected gateway and carrier response.
After a documented change, repeat the failed call and a known working route. Verify the intended caller identity and two-way audio. This guide is based on platform documentation; no live gateway, carrier account or packet capture was tested.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- FreeSWITCH: Call-Setup Failures ↗
- FreeSWITCH: Diagnostic Toolbox ↗
- FreeSWITCH: Gateways and Trunk Registration ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.