MOQ Beta | Now Open For Enterprises / Learn More
explore
Resources
more
legal
support
Industries
Truetime Solutions™
Truetime Solutions™
Meetings Host real-time meetings, collaborate live, and broadcast anywhere.
Products
Resources
Technology
Partners
Red5 Pro
Red5 Cloud
Red5 Pro
Red5 Cloud

Red5 Documentation

 

MOQ Troubleshooting
Discuss on Slack

MOQ Troubleshooting

Enabling Debug Logging

Add the following logger entries to your Logback configuration (conf/logback.xml or equivalent):

<logger name="org.red5.io.moq" level="DEBUG" />
<logger name="org.red5.server.net.moq" level="DEBUG" />
<logger name="org.red5.server.net.webtransport" level="DEBUG" />
<logger name="com.red5pro.moq" level="DEBUG" />

Restart the server after changing the logging configuration.

Successful Connection Log Output

A successful WebTransport client connection produces these three log lines:

INFO  o.r.s.n.p.PicoquicMoqBridge - Picoquic session established: sessionId=1, type=webtransport, path=/moq
INFO  o.r.s.n.p.PicoquicMoqBridge - Picoquic-MoQ bridge created: picoquicSessionId=1, moqSessionId=picoquic-1, type=webtransport
INFO  o.r.s.n.p.PicoquicMoqBridge - WebTransport connection: stream 4 will be control stream

Common Issues

Plugin Does Not Start

Symptom: No MOQ-related log output after server startup.

Resolution: Confirm the moq-plugin directory is present in plugins/ and contains the plugin JAR. Verify enable=true in conf/moq-plugin.properties.

Port Not Reachable

Symptom: Clients time out; cannot connect.

Resolution: MOQ uses QUIC over UDP. Confirm UDP port 4433 (or your configured server.port) is open in your firewall or security group. TCP-only rules are insufficient.

Browser WebTransport Connection Fails

Symptom: Browser console shows Failed to construct 'WebTransport' or cross-origin policy errors.

Resolution:

  1. Confirm the corsConfig bean in conf/red5pro-activation.xml includes Cross-Origin-Opener-Policy, Cross-Origin-Embedder-Policy, and Cross-Origin-Resource-Policy in allowedHeaders, and that coepValue, coopValue, and corpValue are configured. See Configuration.
  2. For self-signed certificates, confirm the serverCertificateHashes value in your client matches the certificate currently in use. The correct hash is printed at server startup.

Authentication Rejected

Symptom: Clients receive SUBSCRIBE_ERROR or PUBLISH_ERROR responses.

Resolution: If auth.cat.enabled=true, verify the token’s HMAC signature matches auth.cat.shared.secret. If auth.cat.allow.anonymous=false, all clients must supply a valid token. Adjust clock skew tolerance with auth.cat.expiration.tolerance if token expiry errors appear.

WebSocket Fallback

When QUIC/UDP is unavailable (for example, in restrictive corporate networks), the relay supports a WebSocket tunnel fallback. Enable it with websocket.tunnel.enabled=true and ensure WebSocket traffic is permitted on the Red5 Pro HTTP/HTTPS ports.

H.265 or Enhanced Video Does Not Play

Symptom: A MoQ-sourced stream connects, but H.265 video is missing, black, or reported as the wrong codec downstream.

Resolution:

  1. Confirm the MoQ catalog advertises the video track codec as H.265/HEVC, for example a codec string beginning with hvc, hev, or containing h265.
  2. For LOC-packaged content, confirm initData contains the raw codec configuration for the track. For CMAF-packaged content, confirm the initialization segment contains the expected codec configuration box.
  3. In Red5 Pro logs, look for messages that the catalog-derived video configuration was deferred until the ProStream was ready, then sent after stream startup.
  4. If the source enters Red5 Pro through Enhanced RTMP before MoQ publishing, confirm the video packet FourCC is hvc1 for H.265/HEVC or av01 for AV1.