How to Debug and Trace MoQT Player Issues

You’ve built a MoQT player (or integrated one) and something isn’t working. Playback stalls. Subscriptions fail silently. Objects arrive but the player doesn’t render them. The relay closes the connection with an opaque error code.

If you’ve worked with HTTP-based video (HLS, DASH), you know how to debug it — open the Network tab, inspect manifest requests, check segment responses. But MoQT is a binary protocol over QUIC streams. The browser’s Network tab doesn’t understand it. You’re flying blind.

This guide shows you how to use the WebTransport Inspector browser extension to diagnose the most common MoQT player issues — step by step, entirely within your browser’s DevTools.

Install the extension

WebTransport Inspector is a free browser extension that adds a MoQT-aware panel to your browser’s DevTools.

1. Install for your browser:
   • Chrome Web Store (also works in Edge, Brave, and other Chromium browsers)
   • Firefox Add-ons
2. Open DevTools (F12 or Cmd+Opt+I on macOS)
3. Navigate to the WebTransport Inspector tab

That’s it. No proxy to configure, no server-side changes, no extra processes to run.

Verify the connection is established

The first thing to check when a MoQT player isn’t working is whether a WebTransport connection was established at all.

1. Open or reload the page with the MoQT player
2. In the WebTransport Inspector panel, look at the connection list in the sidebar
3. Each connection shows its URL, status (open/closed), and the detected MoQT draft version

What to look for:

• No connections visible? The player may not be creating a WebTransport session. Check the browser console for connection errors.
• Connection shows “closed” immediately? Check the close reason — it might be a TLS certificate issue, a CORS problem, or the relay rejecting the client setup.
• Connection is open but no draft version detected? The extension auto-detects the MoQT draft from the CLIENT_SETUP message. If detection fails, the connection may not be using MoQT, or the handshake may be stalling.

If you opened DevTools after the page loaded, the extension may show a mid-session warning banner and still pick up active connections.

Inspect the MoQT handshake

Once you see an open connection, click on it and go to the Messages tab to see the control message log.

1. Look for the CLIENT_SETUP message (sent by the player) and the SERVER_SETUP message (sent by the relay)
2. Expand each message to see the negotiated parameters — supported versions, role, max subscribe ID, path

Common issues:

• No CLIENT_SETUP? The WebTransport session opened but the player never sent its setup message. This is a player bug.
• No SERVER_SETUP response? The relay may be rejecting the connection silently or timing out.
• Version mismatch? The setup messages will show which draft versions were proposed and accepted. If the relay doesn’t support the player’s draft version, the connection may close after setup.

Diagnose subscription failures

Most MoQT player issues boil down to subscriptions — the player subscribes to audio and video tracks, and if those subscriptions fail or stall, playback breaks.

Using the Tracks tab

Switch to the Tracks tab for a high-level view of all subscriptions:

1. Each track shows its namespace, track name, status (pending, active, error, done), and direction (TX/RX)
2. Use the “Active only” filter to hide completed or errored tracks and focus on what’s live
3. Use “Group by NS” to organize tracks by namespace — most players subscribe to multiple tracks under a shared namespace (e.g., one for audio, one for each video quality)

What to look for:

• Tracks stuck in “pending”? The SUBSCRIBE was sent but no SUBSCRIBE_OK or SUBSCRIBE_ERROR came back. The relay may be slow, or the track may not exist.
• Tracks in “error”? Expand the track to see the error reason. Common: Track does not exist, Unauthorized, or the relay’s max subscribe ID was exceeded.
• Tracks in “done” unexpectedly? The relay sent SUBSCRIBE_DONE, which means it stopped sending objects. Check the reason — it might be Track ended, Publisher left, or an internal error.

Timing matters: The timestamps on each track show you exactly how long the relay took to respond. A slow SUBSCRIBE_OK may mean the relay is waiting for the publisher to connect.

Using the Messages tab

For more detail, switch to the Messages tab and look at the subscription lifecycle:

1. Find SUBSCRIBE messages sent by the player (marked with ↑)
2. Look for the matching SUBSCRIBE_OK or SUBSCRIBE_ERROR response (marked with ↓)
3. If a subscription was accepted, look for subsequent SUBSCRIBE_DONE or SUBSCRIBE_UPDATE messages

Trace stalled playback

The player is subscribed and objects should be arriving, but playback stalls. This is the hardest class of problem to debug without a protocol-aware tool.

Check stream activity

Switch to the Streams tab:

1. Look for data streams associated with the subscribed tracks
2. Each stream shows its direction, byte count, and chunk count
3. Use the footer stats bar to see total TX/RX bytes and stream counts

What to look for:

• No data streams for a subscribed track? The relay accepted the subscription but isn’t delivering data. The publisher may not be sending, or the relay may have an internal routing issue.
• Streams are present but byte counts are low or stopped growing? The publisher may have paused, or a QUIC flow control window may be stalling delivery.
• Many streams opening and closing rapidly? This can indicate a mismatch between the publisher’s group/object structure and what the player expects.

Check datagram delivery

Some MoQT implementations use WebTransport datagrams for low-latency delivery instead of streams. The extension intercepts these too:

1. In the Streams tab, look for entries with negative IDs — these are datagram groups
2. Each datagram group shows the track alias, group ID, and byte totals
3. Click to inspect individual datagram payloads

If the player expects stream delivery but the relay is sending datagrams (or vice versa), playback will break silently.

Inspect media payloads

When objects are arriving but the player can’t render them, the problem is usually in the payload format.

Media format detection

Click on a data stream to open the stream data viewer. The extension auto-detects the content type:

• CMAF — Common Media Application Format segments (used by most MoQT video implementations)
• LOC — Low Overhead Container
• fMP4 — fragmented MP4 variants
• CBOR — Concise Binary Object Representation (used by some signaling/catalog tracks)
• MessagePack — binary serialization (used by some catalog implementations)
• JSON — plain JSON (catalog tracks in some drafts)

The streams list shows the detected variant with box count — for example, CMAF(3) means 3 ISO BMFF boxes were found (hover for box names like ftyp, moov, mdat).

Hex viewer deep inspection

For binary payloads, switch to the hex viewer:

1. Object boundary banners appear inline between MoQT objects, showing content description and byte offset
2. Use the object navigator (‹ 1/5 ›) in the sticky bar to jump between objects
3. Byte-level annotations highlight MoQT framing headers, object boundaries, and payload regions in distinct colors

Common issues:

• First object is an initialization segment but player doesn’t process it? Check if the init segment has the expected codec boxes (avc1, hev1, mp4a, Opus).
• Objects contain only mdat boxes without moof? The publisher may be sending LOC-style objects. Check if the player expects CMAF-style segments with both moof and mdat.
• CBOR/MessagePack payload on a track the player treats as media? The player may be subscribing to a catalog track by mistake, or the namespace structure changed.

Export a trace for deeper analysis

If the issue is intermittent or you need to share it with your team:

1. Click the export button in the WebTransport Inspector toolbar
2. The session is saved as a .moqtrace file — a complete recording of all control messages, stream data, object headers, and datagram payloads
3. Share the file with colleagues — they can import it into their own WebTransport Inspector or into moqtap Desktop for deeper analysis with QUIC transport stats

Traces are timestamped to microsecond precision and include the full decoded message content, making them ideal for bug reports and post-mortem analysis.

Use recording controls during long sessions

For long-running player sessions (live streams, 24/7 channels), you don’t want the extension to accumulate unlimited data:

1. Use the recording toggle (red dot) in the Streams tab to pause data capture — control messages and track lifecycle still update, but stream payloads stop accumulating
2. When you’re ready to investigate, resume recording
3. Use the clear button to wipe accumulated stream data and free memory without losing the session state

Summary

Here’s a quick checklist for debugging MoQT player issues:

Symptom	Where to look	What to check
No playback at all	Connection list	Is there an open WebTransport connection?
Connection drops immediately	Messages tab	CLIENT_SETUP/SERVER_SETUP exchange, close reason
Player connects but no media	Tracks tab	Are subscriptions stuck in pending or errored?
Subscriptions active but playback stalls	Streams tab	Are data streams present? Are bytes growing?
Objects arrive but don’t render	Stream data viewer	Is the media format what the player expects (CMAF vs. LOC vs. fMP4)?
Intermittent issues	Trace export	Export a .moqtrace file and analyze offline

Get started

Install the WebTransport Inspector for free:

• Chrome Web Store
• Firefox Add-ons

For native QUIC debugging, QUIC transport stats, and active subscribe/fetch capabilities, see moqtap Desktop. Read the full extension documentation at WebTransport Inspector docs.