Skip to content

Troubleshooting

Access to the FreeSwitch console

# fs_cli im Container
docker exec voicebot-fs fs_cli -H 127.0.0.1 -P 8021 -p voicebot2024

Do not change password

The ESL passwordvoicebot2024is also used by the Platform API for the ESL connection. A change must take place simultaneously at both points.

Diagnostic commands

Gateway status pruefen

# Alle Gateways anzeigen
sofia status

# Erwartete Ausgabe:
# external-ipv4    sip:mod_sofia@46.4.96.105:5060  RUNNING (0)
# internal         sip:mod_sofia@[::]:5060          RUNNING (0)

# Gateway-Details eines Profils
sofia status profile internal

# Registrierte Extensions
sofia status profile internal reg
Status Importance
REGED Gateway is registered (1&1)
NOREG No register required (Plusnet) — *no error! *
FAIL_WAIT Registration failed, waits for Retry
TRYING Registration runs

SIP-Trace

# SIP-Trace einschalten (KURZZEITIG!)
sofia global siptrace on

# SIP-Trace ausschalten
sofia global siptrace off

SIP-Trace just short

SIP trace generates enorme amounts of data in the log. Switch on only for targeted troubleshooting and immediately deactivate it. When forgetting, the hard drive can be full.

Audio debug

# Audio-Debug fuer einen aktiven Call
uuid_debug_media <call-uuid> both on

# Aktive Calls anzeigen
show calls
show channels

Log analysis

# FreeSwitch-Logs im Container
docker logs voicebot-fs --tail 100 -f

# Platform API Logs (SIP-Modul)
docker logs xynap-platform-api --tail 100 -f | grep -i sip

# LiveKit-Logs
docker logs livekit --tail 100 -f
docker logs livekit-sip --tail 100 -f
docker logs livekit-agent --tail 100 -f

Common problems

1&1: 503 Service Unavailable

Symptom: Gateway showsFAIL_WAIT, registration fails with 503.

Ursache: 1&1 blocks Hetzner IPv4 addresses.

** Solution**

  1. Ensure that the trunk is assigned to the profileinternal(dual stack with IPv6)
  2. ext-sip-ipandext-rtp-ipin theinternalprofile must be on2a01:4f8:140:829d::2
  3. Outbound proxy must be IPv6:[2001:8d8:104:100:212:227:124:129]
# Pruefen, ob IPv6 korrekt konfiguriert ist
sofia status profile internal
# ext-sip-ip muss 2a01:4f8:140:829d::2 zeigen

1&1: 401 Unauthorized (despite correct credentials)

Symptom: Registration fails, although username and password agree.

Ursache: Fake Realm configured.

** Solution: The Realm must besip.1und1.de, not**1und1.de.

Plusnet: 408 Request Timeout

Symptom: Proceeding calls to Plusnet break with timeout.

Ursache: DNS Round-Robin — INVITE and ACK land on different servers.

Solution: Outbound proxy92.197.176.16must be set.

Incoming calls do not arrive (CallsIN = 0)

Symptom: Gateway showsREGEDorNOREG(status OK), but no incoming calls.

Checkliste:

  1. UFW check: Are the provider IPs enabled for Port 5060/udp? 

    sudo ufw status | grep 5060

  2. IPv6 fire check (for 1&1): 

    sudo ufw status | grep 2001:8d8

  3. FreeSwitch ACL check: Is the provider IP entered in the ACLsip-gateways?

  4. SIP-Trace aktivierenand see if INVITEs arrive at all

No audio (one-way or both sides)

Symptom: Call is built but no audio audible.

Ursache: Incorrectext-rtp-ipin the Sofia profile.

Checkliste:

  1. ext-rtp-ip check: Must fit the IP version of the provider
  2. Plusnet (IPv4):ext-rtp-ip=46.4.96.105

  3. 1&1 (IPv6):ext-rtp-ip=2a01:4f8:140:829d::2

  4. **RTP ports open? * * 

    sudo ufw status | grep -E "10000|16384"

  5. Audio-Debug aktivieren: 

    # In fs_cli:
uuid_debug_media <uuid> both on
    If no RTP packages are visible → firewall problem. If RTP packages arrive but no Audio → Codec-Mismatch.

WebRTC: No connection setup

Symptom: WebRTC softphone does not connect or REGISTER fails.

Checkliste:

  1. **WSS-Port 7443 available? ** 

    openssl s_client -connect sip.xynap.tech:7443

  2. TLS certificate valid? WebRTC requires a valid TLS certificate.

  3. JsSIP Race Condition: WebSocket must be fully connected before REGISTER is sent. Check browser console for errors.

  4. ICE Timeout: If ICE-Gathering fails, it is usually a restrictive client firewall.

Platform API: xml-curl delivers empty response

Symptom: FreeSwitch cannot load extensions/gateways. New trunks don't appear.

Checkliste:

  1. **API available? * * 

    curl -s http://127.0.0.1:8001/api/v1/sip/live-status

  2. Check API logs 

    docker logs xynap-platform-api --tail 50 | grep xml-curl

  3. ESL connection active? The Platform API shows in the log whether the ESL connection is.

  4. Manueller xml-curl Test: 

    curl -X POST http://127.0.0.1:8001/api/v1/sip/xml-curl \
  -d "section=directory&domain=sip.xynap.tech"

LiveKit Agent does not reply

Symptom: Call is forwarded to*99/ LiveKit, but no agent participates.

Checkliste:

  1. **Agent container running? * * 

    docker ps | grep livekit-agent

  2. Agent-Logs: 

    docker logs livekit-agent --tail 50

  3. SIP-Bridge-Logs: 

    docker logs livekit-sip --tail 50

  4. LiveKit-Room created? Check if the SIP-Call creates a room: 

    docker logs livekit --tail 50 | grep room

Restart order

In case of a complete restart of the telephony stack, keep this order:

# 1. Platform API (muss zuerst laufen fuer xml-curl)
sudo docker compose -f /etc/xynap/stack/docker-compose.yml restart xynap-platform-api

# 2. Warten bis API antwortet
sleep 10
curl -s http://127.0.0.1:8001/api/v1/health

# 3. FreeSwitch
sudo docker compose -f /usr/local/xynap/voicebot/docker-compose.yml restart voicebot-fs

# 4. LiveKit Stack
sudo docker compose -f /usr/local/xynap/voicebot/docker-compose.yml restart livekit livekit-sip livekit-agent

Note order

FreeSwitch needs the platform API when starting for gateway discovery. If FreeSwitch starts before the API, no gateways are loaded. In this case, ansofia profile internal restartandsofia profile external-ipv4 restarthelp in the fs cli.

Quick-Reference: fs cli commands

Command Description
sofia status View all profiles and gateways
sofia status profile internal reg Registered clients
sofia profile internal restart Reload internal profile
sofia profile external-ipv4 restart Reload external profile
sofia global siptrace on/off SIP-Trace on/off
show calls Active Calls
show channels Active channels
uuid_debug_media <uuid> both on Audio debug for a call
reloadxml Reload XML configuration
reload mod_xml_curl reload xml-curl module
originate sofia/internal/1000@sip.xynap.tech &echo Test Call to Extension 1000