Troubleshooting

Data API errors

401 Unauthorized

The bearer token is missing, malformed, or revoked.

• Token format must be sb_d_<streamboardId>_<secret>. Anything else is rejected at parse time.
• Token-board mismatch: the token’s embedded id must match the URL’s streamboard id. If you minted a token for board A and POST to board B, you get 401.
• Revoke + remint: open /app/s/<id>/tokens, delete the token row, mint a new one. The old token is rejected immediately (no grace period).

403 Forbidden

Token is valid, but the request isn’t allowed.

• Board belongs to a different org than the token. (Rare — usually means you grabbed the wrong token from your secrets manager.)
• The board was moved between orgs (admin action). Remint a token from the new org.

413 Payload Too Large

State envelope body exceeded 64 KB. The cap is per-push.

• Trim the largest array (often orders.rows or a series.points list). Pre-aggregate server-side.
• If you genuinely need >64 KB, split into multiple boards (one per dashboard panel) — each board has its own envelope.

429 Too Many Requests

Rate limit. Three layers:

• Per-token: 60 push/min
• Per-board: 600 push/min
• Per-org: 6000 push/min

Back off + retry with jitter. If you legitimately need higher throughput, contact support — the limits are per-account configurable.

”I push, the viewer doesn’t update”

99% of the time this is a $bind typo.

1. Open /s/<id> and view source — find a $bind: "<path>" reference.
2. Call get_streamboard_data (MCP) or GET /api/data/v1/streamboards/<id> (HTTP) — inspect the keys present in the state envelope.
3. Compare. $bind: "kpis.mrr.value" expects exactly { kpis: { mrr: { value: ... } } } in state.

If the bind path is correct but the value is still stale, force-reload the viewer (Cmd+Shift+R) — Cloudflare’s edge cache holds the rendered HTML for ~60s by default.

MCP auth errors

”Token expired, please re-authenticate”

OAuth refresh-token flow. From the MCP client:

> /mcp reconnect streamboard

If that doesn’t work, remove and re-add the server:

claude mcp remove streamboard
claude mcp add streamboard --transport http https://mcp.usestreamboard.com/mcp

You’ll be redirected through the OAuth consent flow again.

”Component not enabled for this org”

Specs reference components by name. If the model authors a spec using BigChart and your org’s catalog allowlist doesn’t include BigChart, the write is rejected.

Fix in Settings → Components: enable the catalog you need. The allowlist is baked into the MCP token at OAuth mint AND re-checked on every write (defense in depth).

Viewer errors

Blank page

• Check the browser console. Most common cause: a component the spec references isn’t installed in the deployed renderer bundle.
• Verify the board id in the URL is correct — typos return 404 (not blank).

”This streamboard is private”

You’re signed out, or signed in to a different org than the board’s owner. Sign in with the right account or ask the owner to make it public.

Still stuck?

mailto:support@usestreamboard.com — include the streamboard id, the request id from the error response (X-Request-Id header on every API call), and a one-line repro.