Troubleshooting the desktop app
Logs
Two files in the app's data folder (see the install page for your platform): local-server.log for the bundled server and tunnel.log for sharing. Attach the relevant one when you open an issue.
The device world
Start with Settings, Help and maintenance, Troubleshooting. Check files verifies the bundled server files, and Repair puts damaged or missing files back while preserving campaigns, pictures, installed worlds and sign-ins. Leave the table first if the repair needs to restart the world. Clear cached files refreshes files fetched from remote hosts without forgetting those hosts.
The same card has a diagnostic report to copy for a bug report. Reset the app is a separate last step behind a typed confirmation: it sets the world's data, installed packs, saved hosts and sign-ins aside in a dated folder, then restarts empty. Nothing is deleted; the retained folder includes recovery instructions. Installed local AI engines stay.
| Message | What to do |
|---|---|
| The local server did not become healthy in time | Quit fully and relaunch. If it repeats, check installation and read local-server.log. |
| The local server exited during startup | Use Check files, then Repair. Keep the log if the check passes but startup still fails. |
| The local server stopped unexpectedly | Relaunch; a halted turn can be retried from the Lead tab. |
| No free local port for the bundled server | Close other local servers or reboot. |
| This build has no bundled server payload | Reinstall a packaged release that includes the server. |
Sharing online
| Message | What to do |
|---|---|
| Downloading the tunnel helper (cloudflared) failed | No internet, or GitHub is blocked. Check the connection and try again. |
| The tunnel helper download was cut short, or corrupted | Try sharing again; the app re-downloads. |
| The tunnel never reported its address, or cloudflared exited during startup | Read tunnel.log. A firewall that blocks outbound connections on unusual ports is the usual cause. |
| The tunnel's address never appeared in DNS, or came up but never became reachable | A network that intercepts DNS or HTTPS (some corporate and hotel networks). Try another network or a phone hotspot. |
| The share tunnel closed unexpectedly | The connection dropped. Share again; the same host code comes back. |
| Sharing online is not supported on this platform yet | macOS. Share on this Wi-Fi still works for a table in the same room. See Install on macOS. |
| Another device holds this room code | A second device or an old install claimed your host code. Take the new code the lobby or the invite dialog offers. |
Joining and signing in
| Message | What to do |
|---|---|
| No table is online with that code | The host is not sharing. Ask them to open the campaign. |
| That does not look like a server address | Paste a room code, an invite link, or a bare address like play.example.com. |
| Your session expired. Sign in again. | The server invalidated the token (a password change does this). Sign in from the server's row in the drawer. |
| Signups are disabled on this server, or needs an invite code | Ask the administrator for an account invite, or arrive with a live room code. |
| This server has not set up Discord sign-in | Use a username and password on that server. |
| The sign-up form asks for a Setup code | The server has no accounts yet, and its first account becomes the administrator. The code is in that server's log; ask whoever runs it. |
Screens and pictures
- The game screens did not load. A host older than server 0.16.0 opens its own pages instead; a host between 0.16.0 and 0.20.x is drawn through portal mode, which the Visiting hosts switch in Settings controls. Turn it on, or update the host.
- Portraits or generated pictures missing while a browser shows them. Fixed in app 0.12.6; update the app. If it persists on a self-hosted server behind Cloudflare, ask the administrator to check that the server's responses are not cached without their origin header.
- A blank window on launch. A GPU driver issue with the embedded browser. Launch once with
--disable-gputo confirm, then update the driver.
The Story AI screen
- An agent program reads "not installed" on Windows although it is. Fixed in app 0.15.5; update the app.
- A big graphics card is offered a small model on Windows. Fixed in app 0.15.5, which reads the card's real memory.
- "The model is unavailable" now and then with a local model. A model server that closed an idle connection; since server 0.26.2 (app 0.17.2) the request is retried once on a fresh connection.
Bluetooth dice
The app opens a small window titled Connect a Bluetooth die when a page asks to pair. Pixels dice bond without a PIN; anything asking for a typed PIN is not a die. On Linux, BlueZ must be running; on Windows, Bluetooth must be on in Settings. A die that disconnects mid-roll falls back to typed entry for that shape.
Still stuck
Open an issue with the app version (Settings, This app), the platform, what you did, what you expected, and the log. For a quick question, ask on the Discord.