Live Updates Troubleshooting

Your app printed a [bridge] Live updates are OFF … message and linked you here. This page explains the reason code in that message: what happened, whose side it is on, and what to do. Every code below has its own anchor, so the link in the console opens the right entry.

What live updates carry

The live channel pushes changes to your UI as they happen:

Plan and entitlement changes: upgrades, downgrades, payment events, quota counters.
Feature-flag flips: they land in about a second.
The plan-changed token refresh: when the plan changes, the session token is refreshed so new entitlements take effect without signing in again.

When live updates are off, none of these arrive until the page is reloaded. Everything else keeps working. Every API call your app makes is unaffected, and a reload always shows current state.

How to tell they are off

The console. The SDK logs one message per episode, not one per retry. It names the reason code, says whose side the problem is on, and ends with a link to this page and a ref:

[bridge] Live updates are OFF — Bridge refused this session's realtime connection (no_token).
  Stopped: plan & entitlement changes, feature-flag flips, the plan-changed token refresh. They appear only after a reload.
  Still fine: every API call your app makes.
  Fix: start live updates after sign-in, …
  https://thebridge.dev/docs/live-updates/troubleshooting/#no_token · ref …

The realtime status. The SDK also exposes the connection status, so your app can show an indicator or report it:

Field	Values	Meaning
`state`	`idle` · `connecting` · `open` · `degraded` · `closed` · `unauthorized`	`open` is healthy. `degraded` means connected, but no channel was accepted. `unauthorized` means Bridge refused the session and the client has stopped retrying.
`reason`	a code from this page	Why it is not `open`. Also the anchor on this page.
`side`	`app` · `config` · `bridge` · `network`	Whose move it is. See the groups below.
`retrying`	`true` / `false`	Whether the client is still trying on its own.
`docsUrl`	a link	This page, at the entry for `reason`.
`hint`	one sentence	The fix, when the SDK can name it (for example the origin to add for `origin_not_allowed`).
`ref`	short id	Identifies this episode for Bridge support.

Each framework SDK exposes this status (in Svelte: realtimeStatusDetail). In development builds the dev badge (“Live updates off — why?”) shows the same reason, side, link and ref.

The ref. A ref names one episode, from the first failure until recovery. The SDK sends it to Bridge with its diagnosis request, so if you contact support, include the ref and we can find exactly what Bridge saw.

Recovery. A refused (unauthorized) client does not retry the same token in a loop. It resumes on its own when the session token changes (for example when a user signs in), when the network comes back, or when the tab is focused again. After you fix a configuration problem, reload the page.

Your app

side: app. Something about how your app handles the session. The fix is in your code.

no_token

What it means: The app subscribed to channels that need a signed-in user (workspace, user or integration events), but there is no session token.
Whose side: Your app.
What to do: Start live updates after sign-in, or give the realtime client the session’s access token (getAuthToken). Signed-out visitors can still receive app-level events such as flag flips.
Still works: All API calls. Changes appear after a reload.

expired

What it means: The session token expired and could not be refreshed.
Whose side: Your app.
What to do: Sign in again. If it keeps happening, check that token refresh works: the framework SDKs pass a refresh hook (refreshAuthToken) for you, so a custom setup needs to do the same, or refresh the session and reconnect. If it happens right after sign-in, check the device clock. A clock far ahead makes a fresh token look expired.
Still works: All API calls that refresh the session themselves. Changes appear after a reload.

malformed

What it means: The value sent as the session token is not a Bridge token. A common cause is an API key, an ID token or some other string used in the browser.
Whose side: Your app.
What to do: Pass the Bridge access token (a JWT) from the signed-in session. API keys belong on your server and must never reach a browser.
Still works: All API calls. Changes appear after a reload.

not_yet_valid

What it means: Bridge saw a token that is not valid yet: its issue time is in the future. This is almost always a clock that is off.
Whose side: Your app.
What to do: Make sure the device’s clock (or your server’s, if it relays tokens) is set automatically. If clocks are correct, contact support with the ref.
Still works: All API calls. Changes appear after a reload.

workspace_mismatch

What it means: The app subscribed to a workspace channel that is not the workspace in the session token. This usually happens after switching workspace without the token catching up.
Whose side: Your app.
What to do: Refresh the session after a workspace switch, then reconnect live updates. Do not build workspace channel names by hand. The SDK derives them from the token.
Still works: All API calls. Changes appear after a reload.

user_mismatch

What it means: The app subscribed to another user’s channel. Usually a different user signed in and live updates were not restarted.
Whose side: Your app.
What to do: Restart live updates when the signed-in user changes (sign-out, then sign-in).
Still works: All API calls. Changes appear after a reload.

app_mismatch

What it means: The app subscribed to integration events for a different Bridge app than the one the session belongs to.
Whose side: Your app.
What to do: Subscribe with the app id the user signed in through.
Still works: All API calls. Changes appear after a reload.

aud_missing_app

What it means: The session token was not issued for this app. Its audience does not include the app id.
Whose side: Your app.
What to do: Use a token from a sign-in through this app, not one minted for another app or by hand.
Still works: All API calls. Changes appear after a reload.

role_not_admin

What it means: The session is not allowed on that channel. Integration events require an OWNER or ADMIN role, and this user has neither.
Whose side: Your app.
What to do: Only subscribe to integration events for owners and admins, or give the user one of those roles.
Still works: All API calls, and every channel the user is allowed on.

unknown_channel

What it means: Bridge did not recognize the channel name. This is a bug in the app or in the SDK, not a setting.
Whose side: Your app (or the SDK).
What to do: If you build channel names yourself, use the SDK’s instead. Otherwise report it to Bridge support with the ref and your SDK version.
Still works: All API calls. Changes appear after a reload.

api_token_scope

What it means: A server-side integration connected with an API token and asked for something other than its own app’s channel (app:<appId>), or tried to publish. API tokens may only subscribe to their own app.
Whose side: Your app (your server).
What to do: Subscribe the API token to app:<its appId> only. Workspace and user channels need a signed-in user’s access token.
Still works: Every API call made with the token.

api_token_inactive

What it means: A server-side integration connected with an API token that Bridge does not accept: revoked, expired, or not an API token of any app.
Whose side: Your app (your server).
What to do: Create a new API token in Bridge admin and deploy it. API tokens belong on your server and must never reach a browser.
Still works: Nothing that uses that token.

Your configuration

side: config. Your app’s Bridge settings disagree with the signed-in session. The console message names both values.

wrong_environment

What it means: The session token was issued by a different Bridge environment than the API your app points at. A typical example is a production token used against stage.
Whose side: Your configuration.
What to do: Point the Bridge API base URL and the sign-in at the same environment. The console message shows both hosts.
Still works: All API calls. Changes appear after a reload.

wrong_app

What it means: The session token belongs to a different Bridge app than the app id your app is configured with.
Whose side: Your configuration.
What to do: Set the app id to the app users sign in through, or sign them in through the configured app. The console message shows both ids.
Still works: All API calls. Changes appear after a reload.

issuer_mismatch

What it means: Bridge found that the token came from another environment. This is Bridge’s version of wrong_environment.
Whose side: Your configuration.
What to do: Make the API base URL and the sign-in use the same environment.
Still works: All API calls. Changes appear after a reload.

origin_not_allowed

What it means: The page’s origin (for example https://app.example.com or http://localhost:5180) is not in the app’s allowed origins. App-level events are open to signed-out visitors, so the origin is what protects them. The same allowlist also blocks sign-in: the SDK’s sign-in form shows “This app’s allowed origins in Bridge don’t include …” and links here.
Whose side: Your configuration. Nothing is wrong in your code.
What to do: In Bridge admin, open Authentication → Security → Allowed Origins and add the exact origin the console message names (scheme, host and port: http://localhost:5180 and http://localhost:5175 are different origins). Then reload.
Still works: Nothing that needs this origin: sign-in from it fails too. Other allowed origins are unaffected.

Bridge’s side

side: bridge. Nothing to change in your app. If it lasts, contact support with the ref from the console message.

refused

What it means: The session token checks out on the client (right format, right environment, right app, not expired), but Bridge refused the connection anyway.
Whose side: Bridge.
What to do: Nothing in your code. Contact support with the ref.
Still works: All API calls. Changes appear after a reload.

anonymous_refused

What it means: Live updates before sign-in are not available on this deployment, so Bridge did not accept a signed-out connection.
Whose side: Bridge. Not a fault in your app.
What to do: Nothing. Live updates start automatically once a user signs in.
Still works: All API calls. Until sign-in, flag flips appear after a reload.

signature_invalid

What it means: The token’s signature did not verify.
Whose side: Bridge, if the token came from a normal sign-in against this environment. Otherwise the token was altered or signed by something other than Bridge.
What to do: Make sure the app sends the token exactly as Bridge issued it. If it does, contact support with the ref.
Still works: All API calls. Changes appear after a reload.

alg_mismatch

What it means: The token is signed with a different algorithm than Bridge expects.
Whose side: Bridge.
What to do: Contact support with the ref.
Still works: All API calls. Changes appear after a reload.

key_config

What it means: Bridge could not load the key it needs to verify tokens.
Whose side: Bridge.
What to do: Nothing in your code. Contact support with the ref.
Still works: All API calls. Changes appear after a reload.

unknown

What it means: Bridge refused the token for a reason it could not classify.
Whose side: Bridge.
What to do: Contact support with the ref.
Still works: All API calls. Changes appear after a reload.

Connection

side: network, or no side. These reasons show up in the realtime status, not as a console link. The transient ones fix themselves.

connection_lost

The connection dropped, typically after sleep/wake or a network change. The client reconnects on its own (retrying: true) and logs once when it is restored. Nothing to do.

server_error

The realtime server reported an error that is not a refusal. It is retried automatically. If it persists, contact support with the ref.

setup_failed

The client could not reach Bridge to set up the connection. It is retried automatically. If it persists, check that the app can reach the Bridge API host.

no_channel_accepted

The client is connected (state: degraded), but Bridge refused every subscription, so no events arrive. The SDK asks Bridge why and, when it can, replaces this code with the channel’s own reason and prints [bridge] Live updates are OFF on channel '…' with a link to that entry: for example no_token, origin_not_allowed or role_not_admin. Fix that one.