calricon.
VoIP & Telecom

The FreeSWITCH mod_spandsp T.38 Fax Trap: Why UDPTL Jitter Fails

Nov 5, 2026/9 min read/Verified Production Playbook

calricon / field note

In enterprise healthcare and financial telephony platforms,

Nov 5, 2026/VoIP & Telecom
319
Advertisement

The FreeSWITCH mod_spandsp T.38 Fax Trap: Why UDPTL Jitter Fails Transmissions

In enterprise telecommunications networks, healthcare electronic health record (EHR) platforms, and financial transaction hubs running FreeSWITCH, Fax over IP (FoIP) remains a non-negotiable compliance requirement. Service providers configure FreeSWITCH using the mod_spandsp module to process high-volume digital faxing—either terminating documents directly to TIFF/PDF storage via rxfax and txfax, or operating as a T.38 gateway (t38_gateway) bridging legacy G.711 audio fax machines to IP-based carrier networks. During initial bench testing with single-page documents across low-latency local networks, transmissions succeed without incident. However, when deployed into live production multi-carrier environments processing high-volume multi-page faxes, a persistent, frustrating failure mode emerges: fax transmissions fail mid-document, typically aborting on page three or four. Physical fax machines emit generic communication error codes (such as Result 49 or Error 54), while FreeSWITCH logs fill with warnings reporting DIS/DTC received 3 times; DCS not recognized, Timer T0/T1 expired, and T.38 transport error, leaving mission-critical clinical prescriptions and legal contracts stranded.

The root cause is unbuffered packet loss and datagram fragmentation within the UDP Transport Layer (UDPTL) combined with missing Error Correction Mode (ECM) configuration. Unlike standard VoIP voice calls, which easily tolerate 1% to 2% packet loss through acoustic packet loss concealment (PLC), analog fax modems (V.17 and V.29 protocols) modulate high-speed analog carrier tones that cannot tolerate missing data during page image transfer. When a call transitions from audio to T.38 via a SIP re-INVITE, FreeSWITCH shifts from RTP to UDPTL. By default, standard FreeSWITCH installations set t38_redundancy = 0 or leave datagram sizes unconstrained. When cloud network paths experience transient packet jitter or out-of-order packet delivery, unredundant UDPTL packets are dropped. A single dropped packet during the modem training check (TCF) or Phase C image transfer disrupts the phase-locked loop (PLL) demodulator. The remote fax terminal fails to acknowledge the image frame, attempts three retries, and abruptly drops the call. Furthermore, if t38_max_datagram exceeds the network Path MTU, IP packet fragmentation occurs, causing entire fax frames to be discarded at upstream carrier firewalls. Without aggressive UDPTL packet redundancy, strict datagram MTU clamping, and mandatory ECM enforcement, IP fax gateways suffer catastrophic multi-page failure rates.



Problem Diagnosis & Root Cause Architecture

To diagnose why FreeSWITCH fax sessions abort during multi-page transmissions, telecommunications engineers must analyze the protocol transition between SIP signaling, UDPTL transport, and analog modem modulation:




  • UDPTL Packet Loss Vulnerability: T.38 encapsulates fax control frames and modem image data inside UDPTL packets. Without forward error correction (FEC) or packet redundancy, any dropped UDP packet on the public internet results in unrecoverable data loss. When transmitting high-resolution images, a missing packet corrupts scan lines, forcing the receiving terminal to reject the page.

  • IP Fragmentation and Path MTU Blackholing: By default, some T.38 endpoints negotiate large maximum datagram sizes (e.g., t38_max_datagram = 1440 or unconstrained). When encapsulated with IP and UDP headers over cloud VPNs or GRE tunnels, datagrams exceed the physical 1500-byte MTU. Because UDP cannot execute TCP-style Path MTU Discovery, fragmented packets are dropped silently by carrier edge firewalls.

  • Modem Training Check (TCF) Failure Loops: In Phase B of the fax handshake, the transmitting terminal sends a 1.5-second burst of high-speed zeroes (the TCF sequence) to verify line quality. If jitter delays UDPTL packet arrival, the receiving demodulator detects bit errors and rejects the rate negotiation (FTT - Failure to Train). The terminals downspeed repeatedly from 14,400 bps to 2,400 bps until hard timeout timers expire.

  • Disabling of Error Correction Mode (ECM): Standard G3 faxing without ECM relies on unacknowledged scan-line streaming. When errors occur, the receiver prints distorted lines or drops the session. Enabling ECM partitions image data into 64-byte or 256-byte frames protected by CRC checks, enabling automatic selective retransmission of missing frames without aborting the call.



The failure mode is particularly deceptive because SIP signaling captures show a completely clean session: both endpoints exchange 200 OK responses, negotiate T.38 SDP attributes, and tear down the call with standard BYE requests. The failure occurs exclusively inside the UDPTL data stream, invisible to high-level SIP monitoring tools.
""",

"""

Why Standard Implementations Fail

Default FreeSWITCH dialplan snippets and community FoIP tutorials fail to implement the defensive parameters required for lossy IP networks.



1. Default Zero Redundancy Settings

In standard configurations, t38_redundancy is left at 0. While zero redundancy saves minimal bandwidth on private LANs, deploying zero redundancy over the public internet or wholesale SIP trunks guarantees fax drops under normal 0.5% internet packet loss.



2. Omitting Explicit ECM Enforcement

Administrators often omit spandsp_ecm_enable in their dialplan logic, allowing endpoints to fall back to legacy non-ECM transmission. In non-ECM mode, even a single dropped packet forces terminal renegotiation failure, whereas ECM transparently retransmits missing frames.



3. Missing Gateway Jitter Buffer Clamping

When operating as a T.38 gateway between audio SIP endpoints and T.38 carriers, FreeSWITCH must decode audio tones into digital T.38 packets. Default configurations allow jitter buffers to fluctuate dynamically, causing timing jitter that disrupts modem tone recognition.

""",

"""

Authenticated Step-by-Step Resolution Playbook

Follow this authenticated engineering playbook to configure robust UDPTL packet redundancy, enforce Error Correction Mode, and clamp datagram MTU sizes in FreeSWITCH mod_spandsp.



Step 1: Configure spandsp.conf.xml for High-Resilience FoIP

Update /etc/freeswitch/autoload_configs/spandsp.conf.xml to establish global modem parameter defaults, enforce ECM, and set optimal audio demodulation levels:



# /etc/freeswitch/autoload_configs/spandsp.conf.xml
<configuration name="spandsp.conf" description="High Reliability T.38 FoIP Configuration">
<settings>
<!-- Enable Error Correction Mode by default -->
<param name="ecm-allowed" value="true"/>

<!-- Supported Modem Speeds: Permit up to V.17 14,400 bps -->
<param name="max-bit-rate" value="14400"/>
<param name="min-bit-rate" value="2400"/>

<!-- Audio tone detection sensitivity -->
<param name="v17-disabled" value="false"/>
<param name="v27ter-disabled" value="false"/>
<param name="v29-disabled" value="false"/>

<!-- Target page resolution -->
<param name="ident" value="Enterprise Secure Fax"/>
<param name="header" value="Enterprise Secure Fax Gateway"/>
</settings>
</configuration>

Enabling ecm-allowed="true" globally guarantees that all local fax terminations leverage frame-level retransmission protocols.

""",

"""

Step 2: Configure Dialplan Variables for UDPTL Redundancy and Clamping

Update your FreeSWITCH inbound and outbound fax dialplan extensions to inject explicit T.38 parameters before invoking rxfax, txfax, or t38_gateway:



# /etc/freeswitch/dialplan/default/01_fax_routing.xml
<include>
<extension name="secure_t38_fax_receive">
<condition field="destination_number" expression="^(8800)$">
<action application="answer"/>

<!-- Enforce Error Correction Mode (ECM) -->
<action application="set" data="spandsp_ecm_enable=true"/>

<!-- Enable T.38 negotiation and reinvite handling -->
<action application="set" data="fax_enable_t38=true"/>
<action application="set" data="fax_enable_t38_request=true"/>

<!-- Enforce 3x UDPTL Redundancy: Send primary + 3 redundant packets -->
<action application="set" data="t38_redundancy=3"/>

<!-- Clamp maximum datagram to 400 bytes to prevent IP fragmentation -->
<action application="set" data="t38_max_datagram=400"/>

<!-- Restrict maximum transmission speed to 14400 bps for stability -->
<action application="set" data="fax_max_rate=14400"/>

<!-- Terminate fax to local PDF/TIFF storage -->
<action application="rxfax" data="/var/spool/freeswitch/fax_in/${uuid}.tif"/>
</condition>
</extension>
</include>

Setting t38_redundancy=3 ensures that every UDPTL packet is duplicated across three subsequent transmissions, allowing the stream to survive up to 30% random packet loss without corrupting the fax frame.

""",

"""

Step 3: Configure T.38 Gateway Mode for Legacy Audio Bridging

If FreeSWITCH acts as a media gateway transcoding G.711 audio faxing from on-premise PBXes to wholesale T.38 carrier trunks, configure the gateway bridge with explicit format pinning:



# /etc/freeswitch/dialplan/default/02_t38_gateway.xml
<include>
<extension name="t38_gateway_bridge">
<condition field="destination_number" expression="^(8801)$">
<!-- Enable T.38 Gateway engine with UDPTL packetization -->
<action application="set" data="t38_gateway_format=udptl"/>
<action application="set" data="t38_redundancy=3"/>
<action application="set" data="t38_max_datagram=400"/>

<!-- Intercept carrier tone detection and execute immediate reinvite -->
<action application="t38_gateway" data="peer"/>

<!-- Bridge call out to wholesale carrier gateway -->
<action application="bridge" data="sofia/gateway/carrier-primary/$1"/>
</condition>
</extension>
</include>

The t38_gateway="peer" directive monitors for fax CNG/CED tones and immediately initiates a clean T.38 reinvite toward the upstream carrier.

""",

"""

Step 4: Tune Operating System Kernel UDP Socket Buffers

Configure the Linux kernel network stack to expand socket receive and send buffers, preventing burst drops during high-speed image transfer. Create /etc/sysctl.d/99-t38-buffers.conf:



# /etc/sysctl.d/99-t38-buffers.conf
# Increase maximum socket buffer sizes to 16MB
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216

# Increase default buffer sizes to 1MB
net.core.rmem_default = 1048576
net.core.wmem_default = 1048576

# Expand network packet backlog queue
net.core.netdev_max_backlog = 10000

Apply the parameters immediately:



sysctl -p /etc/sysctl.d/99-t38-buffers.conf
""",

"""

Step 5: Verify UDPTL Redundancy and Transmission Health in Production

Monitor active fax transmissions, verify UDPTL redundancy packet delivery, and inspect session metrics using FreeSWITCH CLI commands:



# Verify active spandsp module status and configuration
fs_cli -x "spandsp status"

# Trace real-time T.38 variables and negotiated datagram size on active calls
fs_cli -x "uuid_dump <channel_uuid>" | grep -E "t38|fax|spandsp"

# Capture UDPTL traffic to verify 3x redundancy packet delivery
tshark -i any -n -Y "t38" -T fields -e ip.src -e ip.dst -e t38.Type_of_msg | sed 20q

# Inspect FreeSWITCH system log for clean transmission completions
grep -i "fax_success" /var/log/freeswitch/freeswitch.log | sed 20q

Confirm via tshark that UDPTL packets exhibit redundant sequence encapsulation and that uuid_dump reports variable_fax_success=1 upon multi-page document completion.

""",

"""

Delivering mission-critical enterprise Fax over IP requires moving beyond legacy best-effort voice configurations. By configuring 3x UDPTL redundancy, clamping datagram sizes below network MTUs, enforcing Error Correction Mode, and expanding Linux kernel socket buffers, telecommunications engineers eliminate the FreeSWITCH mod_spandsp T.38 fax trap, guaranteeing flawless multi-page document transmission across modern IP telecommunications networks.

"""
Advertisement
Engineering Advisory 48-Hour Audit Turnaround

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.