Part 11: Troubleshooting

The reference chapters document how to configure FreeSWITCH; this part documents how to diagnose it when a call does not behave. It covers the tools FreeSWITCH gives you — the console, sofia status, SIP tracing, logs, and CDRs — and the methodical reads for the failures operators hit most: registrations that fail, calls with no audio or one-way audio, and calls that will not connect. It is about the diagnostic surface, not internals.

📄️Diagnostic Toolbox

Connect with fs_cli, set log levels, inspect channel and SIP-profile state, and trace SIP with the diagnostic commands FreeSWITCH ships with.

📄️Registration Problems

Diagnose why SIP endpoints fail to register with FreeSWITCH: confirm registration state with sofia status and show registrations, then read the common causes — bad credentials, NAT, expiry flapping, and transport mismatch — symptom by symptom.

📄️Audio Problems

Diagnose silent and one-way calls in FreeSWITCH: NAT and firewall RTP failures, advertised media addresses, codec mismatches, and media timeouts, using SIP traces and session variables.

📄️Call-Setup Failures

Diagnose calls that never connect: read Q.850 hangup causes, trace dialplan misroutes, and resolve gateway and originate failures using the FreeSWITCH console.

📄️Reading Traces & CDRs

Capture a Sofia SIP trace, read the SIP transaction at an operator level, and read a cdr_csv record to localize which leg failed and when.