Platform Guide

FreeSWITCH SIP Troubleshooting

9 min read · Updated April 2026

FreeSWITCH is a powerful but complex SIP platform. When calls fail, the answers are in the logs — if you know where to look. This guide covers FreeSWITCH's debug tools, common failure patterns, and how to trace a call from origination to teardown.

In this guide

01Enabling SIP logging in FreeSWITCH 02Essential fs_cli commands 03SIP trace capture 04Common failure patterns 05Sofia SIP profile configuration 06Media and RTP issues

1. Enabling SIP logging in FreeSWITCH

FreeSWITCH uses the Sofia SIP stack. Enable SIP logging via fs_cli:

; Connect to FreeSWITCH CLI
fs_cli -H 127.0.0.1 -P 8021 -p ClueCon

; Enable SIP trace for a profile
sofia profile internal siptrace on

; Enable for all profiles
sofia global siptrace on

; Set log level (0-7, 7=most verbose)
sofia loglevel all 9

; Enable full SIP trace to /tmp/
sofia profile internal capture on

For persistent logging, edit vars.xml and set sofia-sip-trace=yes. SIP messages appear in /usr/local/freeswitch/log/freeswitch.log.

2. Essential fs_cli commands

; Show all active calls
show calls

; Show SIP registrations
sofia status profile internal reg

; Show profile status
sofia status profile internal

; Show active gateways
sofia status gateway

; Show codec list
show codec

; Show channels
show channels

; Trace a specific call by UUID
uuid_debug_media [uuid] both on

; Show channel variables for a call
uuid_dump [uuid]

3. SIP trace capture

Using Homer/HEP capture

; In sofia profile XML
<param name="capture-server" value="udp:homer-server:9060;hep=3;capture_id=100"/>
<param name="capture-calls" value="true"/>

Using ngrep for quick captures

ngrep -W byline -d any port 5060
ngrep -W byline -d any -O /tmp/fs_trace.pcap port 5060

Reading FreeSWITCH SIP log format

FreeSWITCH SIP log entries are prefixed with direction (recv/send), the remote IP/port, and timestamp. Each complete SIP message is logged as a block. Search by Call-ID to follow a dialog through the log.

4. Common failure patterns

Pattern 01

Registration failing with 403

Check that the username in the SIP REGISTER matches the id in the directory XML. FreeSWITCH matches on the auth-username field, not the From header user. Also check that the domain in the REGISTER matches the profile domain. Enable sofia loglevel auth 9 for detailed auth debug.

Pattern 02

Calls failing with "No route to destination"

The dialplan has no matching extension for the dialed number. Check your dialplan XML — verify the context matches what the Sofia profile sets for inbound calls (context parameter in profile). Use show dialplan [number] in fs_cli to test dialplan matching.

Pattern 03

One way audio after call connects

NAT issue — the endpoint is sending RTP to the private IP in the SDP rather than the public IP. Set ext-rtp-ip and ext-sip-ip in the Sofia profile to your external IP. Also check that rtp-rewrite-timestamps=true and rtp-autoflush=true are set in the profile.

Pattern 04

Calls connect but immediately drop

Check for early media issues or ACK routing problems. Use uuid_debug_media to trace the call. Also check that your dialplan bridge action is correctly configured and that the destination endpoint is responding to the INVITE.

5. Sofia SIP profile configuration

Key settings in the Sofia profile XML (conf/sip_profiles/internal.xml):

<settings>
  <param name="sip-port" value="5060"/>
  <param name="context" value="default"/>

  <!-- NAT settings -->
  <param name="ext-rtp-ip" value="auto-nat"/>  <!-- or your public IP -->
  <param name="ext-sip-ip" value="auto-nat"/>

  <!-- RTP settings -->
  <param name="rtp-timeout-sec" value="300"/>
  <param name="rtp-hold-timeout-sec" value="1800"/>
  <param name="dtmf-type" value="rfc2833"/>

  <!-- TLS -->
  <param name="tls" value="true"/>
  <param name="tls-sip-port" value="5061"/>
  <param name="tls-cert-dir" value="/usr/local/freeswitch/certs"/>
</settings>

6. Media and RTP issues

Check RTP port range: FreeSWITCH uses rtp-start-port and rtp-end-port in switch.conf.xml. Default is 16384-32768. Ensure this range is open in your firewall.

Codec passthrough vs transcoding: FreeSWITCH transcodes by default. For passthrough without transcoding, use bypass_media=true in the bridge application. This reduces CPU but loses features like DTMF detection.

RTP statistics during a call:

; Get RTP stats for a live call
uuid_debug_media [uuid] both on

; Show in log output:
; RX: [codec] [packets] [lost] [jitter]
; TX: [codec] [packets]

Frequently asked questions

How do I enable SIP debug logging in FreeSWITCH?

Enable SIP trace in FreeSWITCH using: sofia profile internal siptrace on and sofia global siptrace on from fs_cli. Set sofia loglevel all 9 for maximum verbosity. Logs appear in /usr/local/freeswitch/log/freeswitch.log. For persistent logging set sofia-sip-trace=yes in vars.xml.

How do I fix one way audio in FreeSWITCH?

One way audio in FreeSWITCH is usually a NAT issue. Set ext-rtp-ip and ext-sip-ip in your Sofia profile to your external IP address (or auto-nat for automatic detection). Also verify rtp-rewrite-timestamps=true and rtp-autoflush=true are set in the profile. Use uuid_debug_media [uuid] both on to trace RTP flow on an active call.

How do I troubleshoot FreeSWITCH registration failures?

For FreeSWITCH registration failures, enable sofia loglevel auth 9 for detailed authentication debug. Check that the auth-username in the directory XML matches the username in the REGISTER request. Verify the domain in the REGISTER matches the Sofia profile domain. Check /var/log/freeswitch/freeswitch.log for specific error messages.

Debugging a FreeSWITCH SIP issue?

Paste your FreeSWITCH SIP trace into SIPSymposium. The analyzer parses Sofia SIP log format and identifies registration failures, media path issues, and codec negotiation problems.

Analyze my trace Create free account

Related guides