Troubleshooting

Under pressure? Each scenario below is: Problem, Command, What to look for, Next steps. Copy-paste and go.

Failed Calls

Find every call that never established, then triage by response code.

# All failed calls with Call-ID and response code
sipnab -N -I capture.pcap --filter "state == 'Failed'" --json | jq '.call_id, .status_code'

# Detailed report for one call (Markdown, ready for a ticket)
sipnab -I capture.pcap --call-report "abc123@host" --markdown > report.md

What to look for: sipnab includes response code intelligence – the status field tells you why:

Next steps: If the response code is 408 or you see high retransmits, the problem is network-level – check connectivity and firewall rules before touching SIP config.

One-Way Audio

One direction of RTP has zero packets. The caller can hear the callee (or vice versa) but not both.

# Find calls flagged for one-way audio
sipnab -N -I capture.pcap --filter "one_way == true" --json

# Full diagnostic output
sipnab -N -I capture.pcap --filter "one_way == true" --report

What to look for:

• nat_mismatch == true alongside one_way – the Contact/Via IP doesn’t match the packet source. This is the most common cause.
• Codec asymmetry in the SDP offer/answer (one side offers a codec the other doesn’t support).
• RTP ports in the SDP that never receive traffic (firewall blocking the return path).

Next steps:

1. Check NAT: sipnab -N -I capture.pcap --filter "one_way == true AND nat_mismatch == true" --json
2. If NAT is the cause: enable fix_nated_contact / fix_nated_register on the proxy, or deploy a TURN server.
3. If NAT is clean: verify symmetric RTP, check for SIP ALG on intermediate firewalls (disable it), and confirm both endpoints negotiate a common codec.

Poor Call Quality

MOS below 3.0 means quality degradation users will notice. Below 2.5, calls are unusable.

# Find completed calls with poor MOS
sipnab -N -I capture.pcap --filter "rtp.mos < 3.0" --json

# Live monitoring -- alert on quality or jitter spikes
sudo sipnab -N -d eth0 --filter "rtp.mos < 3.0 OR rtp.jitter > 50" --json

What to look for:

Next steps: If jitter is high but loss is low, the problem is buffering or path instability (check for Wi-Fi hops, VPN tunnels, or missing QoS marking). If loss is high, run a path MTR/traceroute to find where packets are dropping.

Deep-dive with Stream Detail

In the TUI, navigate to a call’s flow view and press Enter on an RTP bar (or press r to jump to the streams list, then Enter on a stream) to open the Stream Detail view. This shows:

• MOS and jitter sparklines – visual trend graphs across the stream’s lifetime, making it easy to spot the exact moment quality degraded.
• Quality intervals – per-interval breakdown of MOS, jitter, and loss so you can correlate degradation with specific time windows.
• Burst/gap analysis (RFC 3611) – distinguishes between bursty loss (congestion events) and gap loss (steady-state impairment). Bursty loss points to queue overflow; gap loss points to a consistently lossy link.
• Silence detection – identifies periods where no RTP was flowing, which can indicate hold events, codec DTX, or network black holes.

This same data is available in the browser analyzer at sipnab.com/analyze/ under the Streams tab.

Slow Call Setup (Post-Dial Delay)

PDD over 3 seconds is perceptible to users. Over 5 seconds and they’ll hang up.

# Find calls with excessive PDD
sipnab -N -I capture.pcap --filter "pdd > 3.0" --json

# Built-in alias with summary report
sipnab -N -I capture.pcap --slow-setup --report

What to look for:

• High retransmits alongside high PDD – the INVITE is being retransmitted because the first one was lost or the remote side is slow to respond.
• DNS resolution delays (common when the proxy does NAPTR/SRV lookups for every call).
• Deep proxy chains adding latency at each hop.

Next steps: Compare pdd with retransmits. If retransmits > 0, the delay is network loss or an unresponsive next hop. If retransmits == 0 but PDD is still high, the downstream server is slow to route (check its logs, database lookups, or LCR table performance).

NAT Traversal Issues

The Contact or Via header advertises a private IP that doesn’t match the actual packet source.

# Find NAT mismatches
sipnab -N -I capture.pcap --filter "nat_mismatch == true" --json

# Built-in alias
sipnab -N -I capture.pcap --nat-issues

What to look for: nat_mismatch == true means the SIP headers contain an IP/port that differs from where the packet actually came from. This breaks return routing for SIP responses and RTP media.

Next steps:

1. Proxy-side: Enable fix_nated_contact and fix_nated_register (OpenSIPS/Kamailio) to rewrite Contact headers with the observed source address.
2. Endpoint-side: Configure STUN/TURN on the phone or softclient so it discovers its public address.
3. Network-side: Disable SIP ALG on every NAT device in the path. SIP ALGs almost always make things worse.

SIP Scanner Detection

Scanners probe for open registrations and try credential stuffing. Detect them early and feed the IPs to fail2ban.

# Live detection with fail2ban-compatible output
sudo sipnab -N -d eth0 --kill-scanner --fail2ban >> /var/log/sipnab/scanners.log

# Find scanner User-Agents in a pcap
sipnab -N -I capture.pcap --filter "ua =~ 'friendly-scanner|sipcli|sipvicious'"

What to look for: Known scanner fingerprints (friendly-scanner, sipvicious, sipcli), high REGISTER rates from a single source, sequential extension enumeration (INVITE to 100, 101, 102…).

Next steps:

1. Point fail2ban at the log file sipnab writes with --fail2ban.
2. For broader detection, combine flags: sudo sipnab -N -d eth0 --kill-scanner --fraud-detect --reg-flood --alert syslog
3. Use --digest-leak to check if any endpoints are leaking credentials in cleartext.

Registration Failures

Phones not registering means no inbound calls and potentially no outbound.

sipnab -N -I capture.pcap --filter "method == 'REGISTER' AND state == 'Failed'" --json

What to look for:

Next steps: A REGISTER that gets 401 followed by a second REGISTER with credentials followed by 200 is healthy. If you see repeated 401s with no successful registration, the password or auth username is wrong. If you see retransmits > 3 on REGISTERs, the registrar may be unreachable.

Generating Reports

Export call data for tickets, post-mortems, or automated pipelines.

# Markdown report for a specific call (attach to a ticket)
sipnab -I capture.pcap --call-report "abc123@host" --markdown > report.md

# JSON export of all failed calls (feed to your monitoring system)
sipnab -N -I capture.pcap --filter "state == 'Failed'" --json > failed_calls.json

# Count failures by response code
sipnab -N -I capture.pcap --filter "state == 'Failed'" --json \
  | jq -r '.status_code' | sort | uniq -c | sort -rn

Quick Browser Analysis

No install, no upload, no data leaves your machine.

Drop a pcap file at sipnab.com/analyze/ – the file is processed entirely in your browser via WebAssembly. The analyzer provides two tabs: Dialogs (SIP call list with flow diagrams) and Streams (full RTP quality data including MOS, jitter, loss, and per-stream detail). Useful for quick triage when you can’t install the CLI, or for sharing a link with a colleague who doesn’t have sipnab.

Export Call Audio

When metrics aren’t enough — export the actual audio to hear what the caller heard.

In the TUI: select a dialog, press F2, Tab to WAV format, type a filename, press Enter.

sipnab decodes G.711 audio (mu-law/A-law) from captured RTP streams and writes a standard WAV file. If the dialog has two RTP streams (one per direction), the export produces a stereo WAV with caller on the left channel and callee on the right.

• Supported codecs: PCMU (PT 0), PCMA (PT 8)
• Buffer: Last ~30 seconds of audio per stream (configurable: [limits] max_audio_frames)
• Output: 16-bit PCM WAV at the stream’s sample rate (typically 8000 Hz)

Open the WAV in any audio player or Audacity.

Still stuck?

Build custom queries with the Filter DSL – 30 fields, regex support, boolean logic. See the CLI Reference for every flag and more recipes.