Platform Guide
OpenSIPS Troubleshooting
9 min read · Updated April 2026
OpenSIPS is a high-performance SIP proxy used by carriers, ITSPs, and large enterprise deployments. When routing fails, registrations don't work, or calls don't connect, the answers are in the logs and the routing script. Here's how to find them.
1. Enabling debug logging in OpenSIPS
; In opensips.cfg — global parameters
debug_mode=yes ; Enable debug mode
log_level=4 ; 1=critical, 2=error, 3=warning, 4=info, 9=debug
log_stderror=no ; Log to syslog
log_facility=LOG_LOCAL0
; Change log level at runtime
opensipsctl fifo log_level 9
View logs
; Systemd
journalctl -u opensips -f
; Syslog
tail -f /var/log/syslog | grep opensips
; Filter by specific Call-ID
grep "abc123" /var/log/syslog | grep opensips
2. opensipsctl and MI commands
OpenSIPS Management Interface (MI) provides runtime inspection and control:
; Show all registered users
opensipsctl ul show
; Show registrations for specific AOR
opensipsctl ul show user sip:1001@example.com
; Show active dialogs
opensipsctl dlg_list
; Show statistics
opensipsctl uptime
opensipsctl get_statistics all
; Reload routing script without restart
opensipsctl reload
; Test routing for a specific request
opensipsctl t_uac_dlg METHOD FROM TO RURI
opensipsctl FIFO commands
; Flush location database
opensipsctl fifo ul_flush
; Show dispatcher status
opensipsctl fifo ds_list
; Reload dispatcher
opensipsctl fifo ds_reload
3. Routing script debugging
Use xlog() to add debug output throughout your routing script:
request_route {
xlog("L_INFO", "[$ci] $rm from $si:$sp to $ru
");
if (is_method("REGISTER")) {
xlog("L_INFO", "[$ci] REGISTER from $fu domain=$fd
");
if (!www_authorize("", "subscriber")) {
xlog("L_WARN", "[$ci] Auth failed for $fu
");
www_challenge("", "0");
exit;
}
xlog("L_INFO", "[$ci] Auth passed, saving location
");
save("location");
exit;
}
if (is_method("INVITE")) {
xlog("L_INFO", "[$ci] INVITE to $ru
");
if (!lookup("location")) {
xlog("L_WARN", "[$ci] User $ru not found in location table
");
sl_send_reply("480", "Temporarily Unavailable");
exit;
}
xlog("L_INFO", "[$ci] Found contact, forwarding to $ru
");
}
t_relay();
}
Key script variables for debugging
$ci = Call-ID
$rm = SIP method
$si = Source IP
$sp = Source port
$ru = Request-URI
$fu = From URI
$tu = To URI
$fd = From domain
$rs = Response status
$err.rcode = Error code (after failed operations)
4. Common routing failures
Issue 01
REGISTER succeeds but INVITE returns 480
The lookup() function can't find the AOR in the location table. Check that the AOR format in the INVITE Request-URI exactly matches how it was registered. AOR matching is case-sensitive and domain-sensitive. Use opensipsctl ul show to verify the registered contact exists.
Issue 02
Authentication loops (401 repeating)
www_authorize() or proxy_authorize() failing despite correct credentials. Check the realm parameter matches the domain in the URI. Verify the subscriber table has the correct password hash. OpenSIPS uses HA1 hash (MD5 of username:realm:password) not plain text passwords.
Issue 03
is_myself() returning false for local domain
The domain isn't in the domain table or the alias list. Run opensipsctl domain showlist to see configured domains. Add missing domains with opensipsctl domain add yourdomain.com. Or check the mhomed parameter if using multiple interfaces.
5. Database issues
; Test database connectivity
opensipsctl db ping
; Check subscriber table
opensipsctl db show subscriber
; Verify location table
mysql -u opensips -p opensips -e "SELECT * FROM location LIMIT 10;"
; Check for connection pool exhaustion in logs
grep -i "db.*error\|cannot.*connect" /var/log/syslog | tail -20
Common database issues: incorrect HA1 password hash in subscriber table, connection pool exhaustion under load (increase db_pool_size), slow queries without indexes (add index on username+domain in subscriber), and stale location entries causing 480 responses.
Frequently asked questions
How do I enable debug logging in OpenSIPS?
Set debug_mode=yes and log_level=4 (or 9 for full debug) in opensips.cfg. View logs with journalctl -u opensips -f or tail /var/log/syslog. To change log level at runtime without restart: opensipsctl fifo log_level 9. Use xlog() in your routing script to add custom debug messages with variable values.
How do I check OpenSIPS registration status?
Use opensipsctl ul show to list all registered contacts, or opensipsctl ul show user sip:1001@example.com for a specific AOR. If an expected registration is missing, check the authentication flow in the logs — failed www_authorize() calls appear as WARN messages. Also verify the AOR format matches exactly between REGISTER and INVITE.
How do I reload the OpenSIPS routing script without dropping calls?
Run opensipsctl reload to reload the routing script without restarting OpenSIPS. Active calls are not affected. For dispatcher reloads use opensipsctl fifo ds_reload. For dialog module reloads use opensipsctl fifo dlg_reload. Module parameters cannot be changed at runtime — those require a full restart.
Debugging an OpenSIPS routing issue?
Paste your OpenSIPS SIP trace into SIPSymposium. The analyzer reconstructs SIP dialogs, identifies routing failures, and detects authentication and location lookup issues.