#Troubleshooting

The problems that actually come up, and what to do about them. The build messages name the file and the problem, so read the whole thing before changing anything. (If an AI assistant is helping, paste it the full error rather than a summary.)

#Setup and access

"Repository not found" when cloning. You don't have access yet. Ask Anthony Kinson or Robert Syvarth to add your GitHub username to the repo, and accept the email invitation before trying again. See submitting your game.

npm isn't a recognised command. Node isn't installed, or the terminal was open before you installed it. Install the LTS build from nodejs.org and open a new terminal.

npm run build fails immediately at the root. Run npm install at the repo root first. The landing page and docs generator need it.

#Building

A manifest error names your game. The message says exactly what's wrong (bad slug, missing index.html, an achievement total over 1000). npm run validate re-runs just those checks, quickly.

"Achievement catalog is out of date". You edited an achievements.json but didn't regenerate the API's copy. Run npm run gen-achievements and commit the result. The Lambda can't read games/ at runtime, so that generated file is the API's only copy.

esbuild or rollup says it was "installed for another platform". This working tree was last used from a different OS. npm run build handles it for the SDK and for games: it stamps each node_modules with the platform that installed it and reinstalls when that changes. If you hit it inside a game's own npm run dev, delete that game's node_modules and npm install again.

Port 8002 is busy. Nothing to fix: npm run preview increments until it finds a free port and prints the URL it settled on.

#Your game doesn't run

Blank page, or images and scripts 404. Almost always absolute URLs. Your game is served from /games/<slug>/, so /main.js looks for a file at the site root that isn't there. Use main.js or ./art/ship.png. In Vite, base: "./" (the template sets this).

The game 404s in preview. build.outputDir in game.json doesn't match where your build actually writes, or there's no index.html at the top of it.

It isn't on the landing page. Check game.json: slug must equal the folder name, and status must be "live" ("hidden" deploys it but hides it from the list).

It worked, then broke after a rebuild. Something in the build now writes somewhere else, or a build step was added that CI can't run. The output must be plain static files with index.html at the top of outputDir.

#Arcade features

"Arcade is not defined". The SDK script didn't load. Two normal causes: the page was opened directly from disk instead of through npm run preview, or you're in a game's own Vite dev server, where /sdk/v1/arcade.js 404s. Both are expected, so keep the typeof Arcade !== "undefined" guard the templates ship with.

Calls throw ArcadeOfflineError. The API is unreachable (offline, or the preview server isn't running). This is by design: catch it and carry on. Leaderboards and achievements are never load-bearing for play.

Sign-in does nothing locally. Locally there's no Google. /api/auth/login mints a session immediately; add ?email=alice@gamesight.io to sign in as somebody else. That shortcut is dev-only and ignored in production. See player accounts.

An achievement unlocks but no popup appears. You're signed out (there's nobody to award it to, and unlock() returns null), you already had it (new: false, which is deliberate), or the game passed achievementToasts: false to Arcade.init. Server-granted unlocks need Arcade.achievements.watch().

Achievements granted from a backend module never show up. Same watch() call. Without it there's no poll, so nothing surfaces until the next page load.

#Working with an AI assistant

Absolute URLs and inventing a backend are by far the two most common. Point at the rule rather than explaining the fix; it's shorter and it sticks.

See also: local development · submitting your game