Troubleshooting the desktop app
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
| Message | What to do |
|---|---|
| The local server did not become healthy in time | The server took more than a minute to start, usually on a first run on a slow disk, or a previous copy is still running. Quit fully and relaunch. If it repeats, read local-server.log. |
| The local server exited during startup (see local-server.log) | Most often a corrupted payload copy after an interrupted update. Quit, rename the local-server folder inside the app's data folder to local-server.old (leave data alone: it is your world's database), and relaunch; the app copies the server again. Then copy public/uploads, public/generated and public/generated-audio from the old folder into the new one, since your uploads and pictures live there. |
| The local server stopped unexpectedly | The server crashed mid-session. Relaunching resumes; a halted turn can be sent back in from the Lead tab. |
| No free local port for the bundled server | Every port the app tries is taken. Close other local servers or reboot. |
| This build has no bundled server payload | A broken download or a build from source without the server. Reinstall from the release. |
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.