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.
Menus, replay identity and departed players
If an in-game or OBS overlay does not return after a menu closes, keep its SDK subscription
alive while hidden. Test menuOpen === true; absence means unavailable. Do not
use pause or replay flags as menu signals. Update to SDK 4.5 for local replay and
observer menu updates, rebuild the app, and restart the desktop to load the recorder.
Both isReplay and isObserver can be true for a recording from an observer slot.
A player leaving does not imply that all their units were destroyed. The current
recorder keeps attributable surviving units visible in observer/replay contexts,
including fresh attachments in standard melee. Custom maps can lack enough
ownership information. See behavior and limits.