Troubleshooting
First open Connection & capabilities in the starter or focused examples. Distinguish URL reachability, SDK connection, synchronized state, match availability, and host capabilities. A reachable HTTP page alone does not prove that the app works.
| Symptom | Likely cause | Next action |
|---|---|---|
| The first run cannot find a command | Unsupported Node version or dependencies missing | Use Node 22.22.3+, run npm install, then npm run dev |
| Port 5173 is occupied | Another development server owns it | Stop that server or explicitly select another port and update Test locally |
init cannot find package.json |
Command ran outside your app | Change into the generated project directory |
| App definition cannot be fetched | Wrong ID, wrong endpoint, or platform unavailable | Copy the client ID from your app record; check connectivity; existing committed bindings remain usable offline |
Import connectW3BoosterApp fails |
Old setup instructions | Import w3boosterApp and call createRuntime() |
| Live mode asks for permission | Opened outside W3Booster or expired/revoked launch | Install/enable the app and launch again through Test locally |
| Local test used to work | The 12-hour override expired | Extend or restart the local test |
APPLICATION_DEFINITION_MISMATCH |
Bundle and database definition differ | Run settings sync, rebuild, redeploy, and launch again |
| Connected but no players | No active match, missing scopes, or incomplete source | Check match.status, granted scopes, and capabilities; do not treat waiting as connection failure |
| Hero/upgrade data is missing | Scope, paid-data entitlement, observer context, or source availability | Inspect capabilities and optional fields; show an unavailable state |
| Window/settings button is disabled | Host unavailable or capability discovery pending | Open an application surface inside W3Booster and inspect host capabilities |
| Overlay is blank | Surface disabled, wrong URL, missing authorization, or no current match | Check app/surface/global switches, use the stable W3Booster OBS source, and inspect browser errors |
| Browser refuses embedding | CSP or X-Frame-Options prohibits the host | Configure the embedding policy for the actual W3Booster host; test application and overlay contexts |
| Reload/HMR breaks a live connection | The launch credential has already been consumed | Reopen the app through W3Booster; never preserve launch tokens in application storage |
| Updated app loads old chunks | Entry document or asset deployment mixed releases | Revalidate HTML; deploy a complete immutable asset set; see publishing guide |
Stable error categories
Use classifyW3BoosterError(error). Permission errors need a fresh authorized launch. Connection errors use stable codes such as UNAVAILABLE, STARTUP_TIMEOUT, or APPLICATION_DEFINITION_MISMATCH. Protocol errors need their code and details. Host-action errors indicate a rejected action. AbortError is expected cleanup, not a user-facing failure.
runtime.start({ timeout: 10000 }) bounds that caller's wait. It does not terminate shared runtime startup; call runtime.stop() if your UI chooses to stop trying. With default retry, show progress and a way to stop instead of an indefinite blank page.
Report a useful issue
Include the SDK version, browser/desktop version, surface, whether demo or live mode is affected, error code, steps to reproduce, and a small code example. Include capability names and connection status when relevant. Remove URL fragments, session tokens, browser-source URLs, and private match/user data.
SDK issues · For example issues, use the issue tracker in the specific example repository.