Troubleshooting & FAQ

If MeshedFlow is installed but not behaving as expected, this page walks the common causes. Start by polling getStats() — the offloadRatio, cdnBytes, and sharedBytes numbers tell you which problem you have.

Offload reads 0%

By far the most common issue, and almost always one of the following:

Your content origin isn’t allowlisted. Signing refuses any URL that isn’t on your tenant’s content-origin allowlist, so no segment verifies and everything falls back to the CDN. Fix: add your segment origin in the portal, or via PUT /control/tenants/:id/origins. The allowlist match is scheme + host (case-insensitive), plus an optional path prefix — make sure the entry matches the host your segments are actually served from. See Content signing & origins and the origins API.
The verification key isn’t reachable. With autoFetchManifestPublicKey on (the default), the SDK fetches the public key from the signaling host. If that fetch fails, peer segments can’t be verified and are rejected. Fix: confirm signalingUrl is correct and GET /manifest/public-key on your host returns the JWK.
requireManifestSignature mismatch. If you’ve turned signature requirements off on the client but expect verified offload — or vice versa — behavior won’t match. Fix: leave requireManifestSignature at its default (true) unless you have a specific reason to change it.
Only one viewer. The mesh needs peers watching near the same position. With a single session there’s no one to share with. Fix: test with several concurrent viewers on the same stream.

TLS / host errors

Wrong scheme or host in the allowlist. The signer compares the segment URL’s scheme and host against the allowlist. An http entry won’t match https segments (and vice versa), and a bare host mismatch fails. Fix: allowlist the exact scheme + host your CDN serves.
Signaling won’t connect. signalingUrl must be a reachable wss:// endpoint with a valid certificate. Fix: verify the wssEndpoint from provisioning and that the port (e.g. :8445) is correct and open.

Symmetric-NAT clients fall back to CDN

STUN-only, clients behind symmetric NAT often can’t form a direct WebRTC data channel and will fall back to the CDN for delivery. This is expected and safe — those viewers still play, they just don’t mesh.

Fix: if a meaningful share of your audience is behind symmetric NAT and you want them participating, bring your own TURN: set allowByoTurn: true and add your TURN servers to iceServers. See Compatibility → NAT and ICE.

401 on sign

A 401 from the signing path means the request had no valid token. Signing requires an authenticated caller because the token’s customerId selects the allowlist — an anonymous sign has no tenant to be scoped to.

Fix: ensure a valid authToken is set on the loader and that it hasn’t expired. See token lifetime and rotation.

Token expiry and rotation

SDK tokens are long-lived (valid for 90 days) because you embed one in a build. When a token expires, authenticated calls start failing.

Fix: issue a fresh token from the portal and ship it in your next build. An already-issued token runs until it expires — rotating doesn’t revoke the old one early, so plan a rollout window. See Authentication → Token lifetime and rotation.

Frequently asked questions

Will viewers notice anything? No. MeshedFlow runs behind the player. If sharing is unavailable or unsafe, the CDN path is used immediately.

How much can we save? It depends on concurrency, geography, bitrate, and event shape. A pilot measures real offloaded bytes and playback quality on your own traffic rather than a generic benchmark.

What happens if a peer is malicious? Only verified media is accepted. Anything that doesn’t match the origin-signed manifest is rejected and the request falls back to your CDN. See Content signing.

Does this replace rights management or packaging? No. MeshedFlow is a delivery layer, not a rights-management layer. It works alongside your existing content protection and never sees decrypted content — your packaging and entitlement workflows stay on your normal path, unchanged.

Can we limit the rollout? Yes. You can constrain a pilot by stream, geography, device class, traffic percentage, or event window, with a rollback path back to normal CDN delivery.

What do we get at the end of a pilot? A measured report showing eligible traffic, offload percentage, playback quality, fallback volume, and the commercial case for expanding or stopping. See Analytics & pilot reports.