# Packet-Level Debugging

> Read a call's SIP ladder from built-in capture, and know when to drop to a raw pcap on the media path.

You can diagnose most call problems from the
[event timeline](/modalities/voice/observability/call-traces) and the
[MOS/jitter/loss](/modalities/voice/observability/mos-jitter-loss) numbers.
Those tell you *what* went wrong. This page is for the times when you must see
the actual packets to understand *why*. Examples: a carrier that tears calls
down at the ring stage, a `488` that you cannot explain, DTMF that never
registers, or audio that flows one way. The telephony leg speaks **SIP** for
signalling and **RTP** for media. The system captures both for you. Thus you
rarely need `tcpdump` at all.

## Signalling is already captured

The system captures every SIP message on every one of your calls
automatically. It keys the messages by `sid` and keeps them in a searchable
store. You reach the store from the console at `agent.firstbyte.fast`. You do
not run a capture agent, mirror a port, or schedule anything. The SIP gateway
mirrors each message when it sends or receives it. Capture uses **HEP** (the
Homer Encapsulation Protocol). This is the same open format that Homer and
other SIP-capture stacks speak. Thus the data is portable. On a self-hosted
deployment, you can point your own HEP collector at the same feed.

> **NOTE:**
> Capture is **tenant-scoped**. You only see calls that belong to your
> workspace. The system filters traces by your tenant and your DID ranges before
> they reach you. Thus a shared managed-cloud plane never leaks another tenant's
> signalling.

What you get per call, without any packet tooling of your own:

- The full **SIP transaction**: every `INVITE`, provisional, `200`, `ACK`,
  `BYE`, re-`INVITE`, and `REFER`, with wire timestamps.
- The **SDP** offered and answered on each leg (codecs, media IP/port, DTMF
  mode). Thus you can see codec and media-path negotiation without any manual
  decoding.
- Both B2BUA legs, lined up under the one `sid`: the carrier-facing dialog and
  the agent/endpoint-facing dialog.

## Reading a ladder diagram

The capture explorer shows a SIP transaction as a **ladder** (a flow diagram).
Each participant is a vertical line. Time runs top to bottom. Every arrow is
one SIP message, annotated with its method or status code and timestamp. For
an inbound call to an AI agent it reads like this:

```
   carrier / SBC              SIP gateway (B2BUA)            agent endpoint
        │                            │                            │
        │ ── INVITE (SDP offer) ────▶│                            │
        │ ◀──── 100 Trying ──────────│                            │
        │                            │ ── INVITE (SDP) ──────────▶│   (only on a
        │                            │ ◀──── 200 OK (SDP) ────────│    human/SIP leg)
        │ ◀── 183 Session Progress ──│                            │
        │        (SDP answer)        │                            │
        │ ◀──── 200 OK (SDP) ────────│                            │
        │ ── ACK ───────────────────▶│                            │
        │ ═══════ RTP media ═════════│════════════════════════════│
        │ ── BYE ───────────────────▶│                            │
        │ ◀──── 200 OK ──────────────│                            │
```

Read the ladder for the things that go wrong:

- **A gap where a message should be.** No `ACK` after the `200 OK`? The dialog
  never confirmed. No `183`/`200` at all after the `INVITE`? Your response
  never reached the caller (loss, an ACL, or an unreachable route).
- **The same message repeated at ~500 ms, 1 s, 2 s intervals.** That is SIP
  retransmission. The sender gets no reply. Follow the arrows to see which hop
  is silent.
- **A `4xx`/`5xx`/`6xx` instead of a `200`.** The code and its reason phrase
  name the rejection. Expand the message to read the headers.
- **The SDP on each side.** Open the `INVITE` and the answering response.
  Compare the `m=audio` lines. A codec list with nothing in common will cause
  a `488`.
- **Timing.** Wide gaps between arrows show where the latency lives. Use the
  ladder timestamps as your first cut before the
  [latency breakdown](/modalities/voice/observability/latency-breakdown).

## Common telephony packet symptoms

<table>
<thead>
<tr><th>Symptom</th><th>Likely cause</th><th>What the ladder / pcap shows — and the fix</th></tr>
</thead>
<tbody>
<tr>
<td>The call rings, then the carrier sends an unsolicited <code>BYE</code></td>
<td>Ringing was signalled with a bare <code>180</code> and no media description</td>
<td>The ladder shows <code>180 Ringing</code> without a <code>183 Session Progress (SDP)</code> after it. The gateway answers early media with <strong>183 + SDP</strong>. If you front your own carrier/SBC, make it send 183 with SDP, not a media-less 180.</td>
</tr>
<tr>
<td><code>488 Not Acceptable Here</code> on answer</td>
<td>No codec in common between the offer and the answer</td>
<td>Compare the two <code>m=audio</code> SDP lines in the ladder. Phone legs must offer <strong>G.711</strong> (PCMU/PCMA). Fix the trunk's offered codecs.</td>
</tr>
<tr>
<td>A <code>401</code>/<code>407</code> challenge loop, the call never sets up</td>
<td>Digest auth fails on a registered endpoint or trunk</td>
<td>The ladder shows repeated <code>INVITE</code> → <code>407</code> → <code>INVITE</code>. Check the endpoint/trunk credentials again. A mismatched secret loops here forever.</td>
</tr>
<tr>
<td>Repeated <code>INVITE</code>s, no response at all</td>
<td>Packet loss, or the ACL blocks the source IP</td>
<td>A silent hop in the ladder. Check that the sender's source IP is allowed and that the route is reachable. See <a href="/modalities/voice/troubleshooting/sip-trunk">SIP trunk troubleshooting</a>.</td>
</tr>
<tr>
<td>The call connects, but audio flows only one way</td>
<td>RTP does not reach one side: a NAT/SDP media address problem, or an asymmetric flow</td>
<td>Signalling looks clean, so this is a <strong>media</strong> problem. Check the SDP <code>c=</code>/<code>m=</code> media address that the far end was told to send to. Then drop to a pcap on the media path (below). See <a href="/modalities/voice/troubleshooting/one-way-audio">one-way audio</a>.</td>
</tr>
<tr>
<td>DTMF digits never register</td>
<td>An RFC 2833 telephone-event payload-type mismatch, or the far end sends in-band</td>
<td>The ladder's SDP shows the negotiated <code>telephone-event</code> PT. Only an <strong>RTP pcap</strong> shows whether the digits actually arrive. Check that both sides agree on RFC 2833 and the payload type.</td>
</tr>
</tbody>
</table>

## When to drop to a pcap

Built-in capture records **signalling** (and RTCP/QoS summaries). It does not
record the raw RTP audio payload. Take a packet capture when the question is
about the media stream itself, and the ladder plus
[MOS/jitter/loss](/modalities/voice/observability/mos-jitter-loss) did not
answer it:

- **One-way or no audio** where signalling is clean. You must see whether RTP
  actually leaves one side and arrives at the other, and on which address.
- **DTMF (RFC 2833)** that is not detected. Inspect the `telephone-event`
  packets and their payload type on the wire.
- **Codec / payload-type drift.** Check that the RTP payload type on the wire
  matches what the SDP negotiated.
- **Loss or jitter patterns** that the E-model MOS score flags but does not
  localize. Packet arrival timing tells you where the gaps are.

  1. **Capture on a box you actually own**
Take the pcap at your **SBC or carrier edge**, or on a self-hosted engine
    host that you control. Do not take it on the managed-cloud media plane.
    Filter to the call's RTP by media IP/port (from the SDP in the ladder)
    plus the SIP signalling port. For example:
    `tcpdump -i <if> -w call.pcap 'udp and (host <media-ip>)'`.
  2. **Open it as a VoIP flow**
Load the pcap in Wireshark. Use <strong>Telephony → VoIP Calls</strong> to
    reconstruct the dialog. Then use <strong>RTP → Stream Analysis</strong> to
    see per-packet loss, jitter, and sequence gaps. Wireshark builds its own
    ladder from the packets. Thus you can line it up against the captured SIP
    trace.
  3. **Match it back to the call**
Correlate on the SIP `Call-ID` (and your `sid`) so that the pcap and the
    built-in capture describe the same call. The media IP/port to filter on is
    the one in the SDP answer that you already read in the ladder.

> **WARNING:**
> **The media plane can be invisible to `tcpdump`.** On the managed cloud, the
> engine can take direct, kernel-bypass ownership of the NIC for the RTP/QUIC
> fast path. Then packets never traverse the kernel stack that a host-level
> `libpcap`/`tcpdump` hooks into. A capture on that box will show little or no
> RTP. Capture at the SBC or carrier edge, or on a switch mirror/SPAN port. Or
> use the built-in SIP capture and QoS telemetry instead. This is why the engine
> does signalling capture for you, and does not leave it to `tcpdump`.

> **WARNING:**
> **Browser and app legs are encrypted media.** A WebRTC/WebTransport leg
> carries audio inside DTLS-SRTP (or a QUIC session). A pcap of it is
> ciphertext. You cannot read the RTP payload from the wire. Debug those legs
> with the [MOS/jitter/loss](/modalities/voice/observability/mos-jitter-loss)
> and [call-trace](/modalities/voice/observability/call-traces) surfaces, not
> with a packet capture. Raw packet-level debugging is a **telephony-leg**
> technique.

## Related

  - **[SIP / RTP debugging](/modalities/voice/observability/sip-rtp-debugging)** — The workflow to isolate a telephony-leg fault, start to finish.
  - **[Call traces](/modalities/voice/observability/call-traces)** — The assembled per-call event timeline, keyed by sid.
  - **[MOS, jitter & loss](/modalities/voice/observability/mos-jitter-loss)** — The media-quality numbers that tell you when to open a pcap.
  - **[Call lifecycle](/modalities/voice/transport-telephony/call-lifecycle)** — What each SIP message on the ladder means, and where the agent attaches.
  - **[One-way audio](/modalities/voice/troubleshooting/one-way-audio)** — The classic media-path fault that a pcap resolves.
  - **[SIP trunk issues](/modalities/voice/troubleshooting/sip-trunk)** — ACLs, auth loops, and unreachable routes at the trunk edge.