Skip to main content

​
Troubleshooting Guide

This guide helps you identify and resolve common issues encountered when integrating with the Qumo Deploy control plane and media relay network.

​
1. Relay & WebTransport Connectivity

​
WebTransport / QUIC Connection Drops or Timeouts

Symptom: Client connection fails during initial handshake or times out when connecting to a relay (e.g. https://cdn.qumo-deploy.com:4433). Causes & Solutions:
  • UDP Port 4433 Blocking: Media over QUIC (MoQ) and WebTransport run on top of HTTP/3 / UDP. Many corporate firewalls and VPNs block outbound UDP traffic on non-standard ports.
    • Fix: Ensure outbound UDP on port 4433 is permitted on your network or security group.
  • WebSocket fails on Safari or iOS: WebKit browsers connect over WebSocket, which the managed relays take with TLS on TCP 443, not on 4433; the relays’ TCP 4433 is closed to the internet. connect dials WebSocket at the URL’s own port unless told otherwise.
    • Fix: Pass webSocketURL with port 443, e.g. connect("https://cdn.qumo-deploy.com:4433/?jwt=…", { transport: "websocket", webSocketURL: "wss://cdn.qumo-deploy.com/?jwt=…" }). See Where your clients connect.
  • Relay Liveness Degradation: Relays that stop sending heartbeats leave discovery. A relay that has not answered yet may still be listed.
    • Fix: Try the relays from discovery in order and move to the next when one does not answer. client.relays.resolve returns the whole list, ending with your relay hostname.
Fallback Pattern

​
2. Authentication & Authorization Errors

​
401 Unauthorized

  • Expired session: Console and qumod login sessions last 7 days. Sign in again.
  • Invalid or expired token: The API host (api.qumo-deploy.com) takes Bearer tokens only and ignores cookies, so a console session does not authenticate there. See Authentication for the credentials each host accepts.
  • Revoked signing key: Managed relays refuse a credential signed by a key you revoked (POST /v1/projects/{id}/signing-keys/{kid}/revoke), and end the sessions that key admitted, within about a minute. Revocation is per key, not per credential: to cut off one client, stop signing credentials for it, and what its current credential grants lapses at its expiry, at most an hour. See Rotation and revocation.

​
403 Forbidden

  • Scope vs. Permission Mismatch: Even if an Identity Token carries the wildcard * scope, the request will fail with 403 if its User or Identity does not hold the required IAM role binding (e.g. roles/project.admin).
  • IP Allowlist Enforcement: If an IP allowlist rule exists on the identity, its tokens are refused from addresses outside those ranges with 403 Forbidden (source IP not in identity allowlist).
  • Missing CSRF Token in Cookie Requests: When calling mutating routes (POST, PUT, PATCH, DELETE) with a session cookie, the client must send the X-CSRF-Token header. Identity Tokens and personal access tokens don’t need it.

​
3. Rate Limits & Billing Quotas (429 vs. 402)

It is critical to distinguish between transient rate limits and billing quota limits:

​
4. CLI Device Flow Timeouts

Symptom: qumod login outputs The code expired before it was approved. Run 'qumod login' again. Cause: The RFC 8628 OAuth 2.0 Device Flow user verification code expires after 15 minutes if unapproved in the browser. Fix:
  1. Run qumod login.
  2. Open the verification URL it prints (https://console.qumo-deploy.com/device) within 15 minutes and enter the 8-character user code (shown as XXXX-XXXX).
  3. For automated environments, skip the interactive flow entirely by exporting QUMO_TOKEN="qumo_pat_...".