Deployment troubleshooting

Blank page or missing assets

• Deploy the built output directory, not the source directory.
• Confirm the configured entrypoint exists with exact letter casing.
• Use relative URLs. For Vite, set base: './'.
• Do not use root paths such as /assets/game.js; they point at the isolated build origin root and often miss framework base assumptions.
• Inspect the Network panel for the first 404 or incorrect MIME type.

npm run build
test -f dist/index.html
inkwell deploy ./dist --game my-game

Loading screen never finishes

New inkwell init configurations use handshake mode. The game must load the SDK or engine wrapper and call Inkwell.ready() after the first playable scene exists. Report a useful failure with Inkwell.loading.fail(message). For an unmodified export with no SDK, use compatible mode.

client: {
  directory: 'dist',
  startup: { mode: 'compatible', timeoutMs: 120000 },
}

Works locally but not in the player

• File names and URLs are case-sensitive after upload.
• Mixed HTTP content is blocked; remote assets must use HTTPS.
• Camera, microphone, geolocation, payments and USB are unavailable in the game frame.
• Top-level navigation and ordinary form submission are sandboxed. Use fetch, the SDK, or an Inkwell backend instead.
• Threaded WASM requires capabilities.threads: true and compatible external resources.

Service worker problems

Register service-worker scripts with relative URLs. Cache only game assets from the current build origin and never intercept or navigate to Inkwell account/game-page routes. During diagnosis, unregister the worker and clear storage for the build origin, then reload the exact preview. Each published build receives a new immutable origin, so do not use a service worker as cross-release save storage.

Backend appears offline or starts slowly

An idle backend starts on demand. Show a connecting state and allow the SDK's 60-second connection window instead of immediately declaring multiplayer unavailable. Persist important world state in D1 or R2 and restore it during start. If connection still fails, distinguish startup, authentication, timeout and application errors in the UI; do not retry non-idempotent actions blindly.

CLI authentication or upload fails

inkwell whoami
inkwell games show --game my-game
inkwell deploy --game my-game

• A 401 means the token is absent, revoked or invalid.
• A 403 usually means creator approval, ownership, consent or preview scope does not permit the operation.
• A 404 can deliberately hide a game/build the account cannot access.
• A 409 is a state conflict such as an unavailable slug or incomplete build.
• A 429 includes a retry interval. Re-run the same deploy to resume verified chunks.

Before reporting a platform fault

Record the game slug, build ID, preview URL, approximate UTC time, browser/version, first console error, first failed network request and whether the same build fails for a named tester. Never include a developer token, runtime credential or server secret.