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 an assigned relay URL (e.g. https://tyo1.relay.qumo.live: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 (and standard UDP 443) is permitted on your network or security group.
  • Relay Liveness Degradation: The control plane monitors node heartbeats. If a relay has missed its heartbeat interval, the credential response marks its status as degraded.
    • Fix: Always inspect the fallback array in your issued credential response (cred.fallback) and automatically retry connection against the secondary edge endpoints.
Fallback Pattern

​
2. Authentication & Authorization Errors

​
401 Unauthorized

  • Expired Session Token: Interactive browser sessions expire after 24 hours. The CLI or frontend will automatically clear invalid tokens on logout.
  • Malformed Secret Key: API keys must follow the format qumo_<env>_<64-hex>. Plaintext keys are shown only once at creation.
  • Revoked Token (jti): If an active credential has been revoked via POST /admin/v1/credentials/{jti}/revoke, all edge relays immediately reject the token via in-memory revocation bloom filters.

​
403 Forbidden

  • Scope vs. Permission Mismatch: Even if an API key carries the wildcard * scope, the request will fail with 403 if the calling principal (User or Bot) does not hold the required IAM role binding (e.g. roles/project.admin).
  • IP Allowlist Enforcement: If an IP allowlist rule exists on the bot or API key, requests originating from unauthorized CIDR ranges will be blocked with 403 Forbidden (ip not allowed).
  • Missing CSRF Token in Cookie Requests: When invoking mutating routes (POST, PUT, DELETE) with a session cookie, the client must echo the X-CSRF-Token header.

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

It is critical to distinguish between transient rate limits and billing quota limits:
Console Screenshot Placeholder:
Screenshot showing the 402 Plan Cap notification banner and the Upgrade CTA button in Stream Studio.

​
4. CLI Device Flow Timeouts

Symptom: qumod login outputs Authorization timed out or expired. Please 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. Ensure you visit the verification URL (https://console.qumo-deploy.com/device) and enter the 8-character user code.
  3. For automated environments, skip the interactive flow entirely by exporting QUMO_TOKEN="sec_...".