Fix Kamailio WebRTC 478 Unresolvable Destination Errors
calricon / field note
Eliminate Kamailio 478 Unresolvable destination and
Fix Kamailio WebRTC 478 Unresolvable Destination Errors
In production WebRTC deployments fronted by Kamailio (such as browser softphones built on JsSIP or SIP.js), registrations succeed while inbound calls, blind transfers, or in-dialog BYE requests fail with 478 Unresolvable destination. Kamailio logs emit ERROR: <core> [resolve.c]: sip_hostport2su: could not resolve hostname: "*.invalid" followed by t_forward_nonack: failure to add branches.
The verified root cause is missing WebSocket NAT-aliasing and destination-URI restoration for RFC 7118 synthetic .invalid hostnames. Browser SIP stacks cannot inspect their local socket IP and therefore advertise random .invalid domains in Contact and Via headers; without aliasing and handle_ruri_alias(), Kamailio attempts public DNS resolution on an unresolvable domain.
Problem Diagnosis & Root Cause Architecture
Kamailio relies on the nathelper and websocket modules to map synthetic browser URIs back to the active TLS/WebSocket TCP connection. Four configuration gaps cause 478 Unresolvable destination failures:
- Missing WebSocket Detection Flag: Standard NAT heuristics skip WebSocket frames unless
nat_uac_test(64)is evaluated to detect signaling arriving over WS or WSS transports. - Unrecorded Source Socket on REGISTER: Calling
save("location")withoutfix_nated_register()(or mismatchedreceived_avpparameters betweennathelperandregistrar) leaves Kamailio with only the.invalidContact URI. - Missing Contact Alias on Replies and INVITEs: Without
add_contact_alias()in bothrequest_routeandonreply_route, downstream PBXs like Asterisk or FreeSWITCH receive a bare.invalidContact and target it on subsequent in-dialog requests. - Skipped R-URI Alias Extraction: In-dialog requests routed via
loose_route()fail when$duis empty unlesshandle_ruri_alias()strips the;alias=ip~port~transportparameter and populates$du.
Never attempt to rewrite WebRTC .invalid Contact headers with fix_nated_contact(); use fix_nated_register() on REGISTER and add_contact_alias() paired with handle_ruri_alias() to preserve RFC-compliant signaling and WebSocket connection reuse.
Why Standard Implementations Fail
1. Using fix_nated_contact() Instead of add_contact_alias()
Overwriting the Contact header directly breaks strict browser SIP stacks that validate their own Contact URI in 200 OK responses and subsequent in-dialog requests.
2. Omitting onreply_route Aliasing for WebSocket Responses
Aliasing only incoming INVITE requests leaves 200 OK responses from WebRTC callees with bare .invalid Contact URIs, causing the caller's ACK or BYE to fail with 478.
3. Mismatched received_avp Between nathelper and registrar
If modparam("nathelper", "received_avp", ...) and modparam("registrar", "received_avp", ...) do not share the exact same AVP name, fix_nated_register() stores the source address where save("location") never reads it.
Step-by-Step Resolution Playbook
Step 1: Verify received_avp Alignment in kamailio.cfg
Ensure both nathelper and registrar reference the identical received_avp parameter so WebSocket source sockets persist in usrloc:
modparam("nathelper", "received_avp", "$avp(RECEIVED)")
modparam("registrar", "received_avp", "$avp(RECEIVED)")Step 2: Apply nat_uac_test(64) and Aliasing Across Routes
Detect WebSocket signaling in request_route, save the received socket on REGISTER, and alias Contacts on both requests and replies:
request_route {
if (nat_uac_test(64)) {
force_rport();
if (is_method("REGISTER")) {
fix_nated_register();
} else {
if (!add_contact_alias()) {
sl_send_reply("400", "Bad Request");
exit;
}
}
}
if (!is_method("REGISTER")) {
t_on_reply("WS_REPLY");
}
route(WITHINDLG);
}
onreply_route[WS_REPLY] {
if (nat_uac_test(64)) {
add_contact_alias();
}
}Step 3: Restore Destination URI in WITHINDLG
Extract the alias parameter into $du inside your in-dialog route whenever $du is empty so Kamailio forwards over the existing WebSocket connection:
route[WITHINDLG] {
if (has_totag()) {
if (loose_route()) {
if ($du == "") {
if (!handle_ruri_alias()) {
sl_send_reply("400", "Bad Request");
exit;
}
}
route(RELAY);
}
exit;
}
}Step 4: Validate Config, Reload, and Inspect Live Bindings
Check syntax, reload Kamailio, and verify that registered WebRTC contacts populate Received and active WebSocket connections:
sudo kamailio -c -f /etc/kamailio/kamailio.cfg
sudo systemctl reload kamailio
sudo kamcmd ul.dump | grep -E "AOR|Contact|Received|Socket"
sudo kamcmd ws.dumpConfirm that every .invalid Contact entry shows a valid Received: sip:IP:PORT;transport=ws (or wss) value and that test calls complete without 478 responses.
Experiencing this issue in your production systems?
Calricon conducts senior-level VoIP, SIP trunking, Asterisk, and cloud infrastructure audits. We review your live configs, identify packet drops or contention bottlenecks, and provide exact remediation runbooks.