Platform Guide
FusionPBX Troubleshooting
8 min read · Updated April 2026
FusionPBX is a multi-tenant web GUI for FreeSWITCH. When calls fail or audio breaks, the diagnosis happens in FreeSWITCH logs and fs_cli. Here is how to navigate FusionPBX to find and fix the most common SIP issues.
1. FusionPBX and FreeSWITCH architecture
FusionPBX is a web-based GUI that configures and manages FreeSWITCH. All actual SIP processing happens in FreeSWITCH — FusionPBX writes configuration files and controls FreeSWITCH via its API.
Key architectural points for troubleshooting:
- FreeSWITCH handles all SIP signaling, RTP media, and dialplan execution
- FusionPBX stores configuration in PostgreSQL and generates XML configs for FreeSWITCH
- After changes in FusionPBX GUI, you must flush the cache for changes to take effect
- Multi-tenant: each domain is a separate tenant with its own extensions and routes
2. Enabling debug logging in FusionPBX
Via FusionPBX GUI
Advanced → Log Viewer shows FreeSWITCH logs in the browser. Set log level to DEBUG for maximum verbosity.
Via fs_cli
; Connect to FreeSWITCH CLI
fs_cli
; Set log level
/log 7 ; DEBUG level (7 = most verbose)
/log 5 ; INFO level (quieter)
; Enable Sofia SIP logging
sofia loglevel all 9 ; Maximum SIP logging
sofia loglevel tport 9 ; Transport-level logging
sofia loglevel nta 9 ; Transaction-level logging
; Disable verbose logging after troubleshooting
sofia loglevel all 0
Log file location
; FreeSWITCH log file
tail -f /var/log/freeswitch/freeswitch.log
; Filter for SIP messages
tail -f /var/log/freeswitch/freeswitch.log | grep -E "INVITE|REGISTER|ERROR"
; FusionPBX application log
tail -f /var/log/fusionpbx/fusionpbx.log
3. fs_cli commands for troubleshooting
; Show all active calls
show calls
; Show registered endpoints
show registrations
; Show SIP profiles
sofia status
sofia status profile internal
sofia status profile external
; Show specific gateway (SIP trunk)
sofia status gateway MY-TRUNK-NAME
; Reload a SIP profile after config change
sofia profile internal rescan
sofia profile external restart
; Show dialplan for a number
show dialplan XML 1001 default
; Trace a specific call
uuid_trace UUID console
; Show endpoint details
sofia status profile internal user 1001@yourdomain.com
4. Registration failures in FusionPBX
Issue 01
Phone cannot register
Enable Sofia logging and capture the REGISTER exchange. Check that the domain in the phone matches a FusionPBX domain. In FusionPBX, go to Accounts → Extensions and verify the extension exists. Check the SIP profile the phone is registering to (internal vs external).
Issue 02
Registration succeeds but calls fail
Check the dialplan context. In FusionPBX, each domain has a dialplan context. The extension must be in the correct context, and the dialplan must have matching rules for the dialed number.
; Check registrations
fs_cli
show registrations | grep 1001
; Check if domain exists in FreeSWITCH
sofia status profile internal
; Look for: Registrations: N (should be > 0 if phones registered)
; Flush FusionPBX cache after changes
Advanced → Flush Cache (in FusionPBX GUI)
; Or via CLI:
fusionpbx flush_cache
5. One-way audio and NAT in FusionPBX
FusionPBX/FreeSWITCH NAT configuration is in the Sofia SIP profile settings:
; In FusionPBX GUI:
; Advanced → Default Settings → Search for "ext-rtp-ip"
; Set ext-rtp-ip to your public IP or $${domain}
; Or via FreeSWITCH vars.xml
; /etc/freeswitch/vars.xml
<X-PRE-PROCESS cmd="set" data="external_rtp_ip=203.0.113.1"/>
<X-PRE-PROCESS cmd="set" data="external_sip_ip=203.0.113.1"/>
; After changing, restart the Sofia profile
fs_cli
sofia profile external restart
sofia profile internal restart
For phones behind NAT registering to FusionPBX, the internal profile handles local phones (no NAT) and the external profile handles remote phones (behind NAT). Phones registering from outside your network should use the external profile port (5080 by default).
6. SIP trunk issues in FusionPBX
; Check gateway (trunk) status
fs_cli
sofia status gateway MY-TRUNK
; Output shows:
; Name: MY-TRUNK
; State: REGED (registered) or NOREG (not registered)
; Ping: OK or FAIL
; Force gateway re-registration
sofia profile external killgw MY-TRUNK
sofia profile external rescan
; Check outbound route in FusionPBX
; Dialplan → Outbound Routes
; Verify the route pattern matches the dialed number format
; Verify the gateway is correct
After any trunk configuration change in FusionPBX GUI, flush the cache and rescan the Sofia profile. Changes to gateways require sofia profile external rescan at minimum, and sometimes a full restart of the external profile.
Frequently asked questions
How do I enable SIP debug logging in FusionPBX?
Connect to FreeSWITCH CLI with fs_cli and run: sofia loglevel all 9 for maximum SIP logging. View logs with tail -f /var/log/freeswitch/freeswitch.log. In the FusionPBX GUI, go to Advanced → Log Viewer for browser-based log viewing. Remember to disable verbose logging after troubleshooting with sofia loglevel all 0.
Why are FusionPBX phones not registering?
FusionPBX registration failures are usually caused by: phone using wrong SIP server IP or port, extension not created in FusionPBX, wrong domain in phone configuration (must match a FusionPBX domain exactly), or cache not flushed after creating the extension (Advanced → Flush Cache). Check registrations with show registrations in fs_cli.
How do I fix one-way audio in FusionPBX?
Set the external IP in FusionPBX: Advanced → Default Settings → set ext-rtp-ip and ext-sip-ip to your public IP. Then restart the Sofia profiles: fs_cli → sofia profile internal restart → sofia profile external restart. Remote phones should register to the external SIP profile (port 5080) not the internal profile (port 5060).
Having FusionPBX SIP or audio issues?
Capture a packet trace from FusionPBX (or use the FreeSWITCH built-in capture) and upload to SIPSymposium for automated diagnosis of registration, codec, and media issues.