# debuff doctor: why won't my game start?

`npx debuff doctor` checks a debuff project's whole setup in one pass and prints a fix for every problem it finds: Node, the debuff package versions, `node_modules`, `debuff.config.ts`, assets, saves, the files agents read and the browser that scenarios use. `--fix` applies the safe fixes and checks again. It never stops at the first problem, because a broken setup usually has more than one.

Here it is on a fresh project with nothing installed and its `.mcp.json` deleted:

```text
◆  Node 24.15.0
◆  package.json found
■  Not installed: @debuffjp/audio, @debuffjp/core, @debuffjp/input, @debuffjp/juice, @debuffjp/cli, typescript, @debuffjp/dev, keiko
│  fix: npm install
■  A package.json script runs tsc, but TypeScript is not installed
│  fix: npm i -D typescript
■  Cannot find module '@debuffjp/cli' imported from 'debuff.config.ts'
│  fix: npm install (the config imports packages that aren't installed yet)
◆  saves.json is valid
▲  AI agents lack project context: missing .mcp.json with the debuff server
│  fix: … .mcp.json needs { "mcpServers": { "debuff": … } }
◆  Agent skills match debuff 0.20.0 (.claude/skills, .agents/skills)
◆  Browser for scenarios, fuzzing and agents: 155.0.8059.85
…

[debuff] 3 problems to fix
         --fix applies the safe fixes
```

`■` is a problem that stops something working, `▲` is advice. Then `npx debuff doctor --fix`:

```text
◇  npm install
◇  wrote .mcp.json
◆  8 packages installed
◆  debuff packages all at 0.20.0
◆  TypeScript is installed
◆  debuff.config.ts loaded
◆  AGENTS.md, CLAUDE.md and .mcp.json are set up for AI agents
…
[debuff] all set
```

## What it checks

| Check | What goes wrong without it |
| --- | --- |
| Node version | debuff needs Node 22 or newer |
| `NODE_ENV` in your shell | `production` turns dev code off under `debuff dev`; `development` makes `debuff build` keep it |
| Installed packages | missing `node_modules`, or installed versions that differ from `package.json` |
| One debuff version | every `@debuffjp/*` package must be on the same version |
| One copy of core | a nested second copy of `@debuffjp/core` gives a package its own `Game` |
| `@debuffjp/dev` | scenarios, fuzzing, the dev panel and agents need its dev hooks |
| TypeScript | a script runs `tsc` but it isn't installed |
| `debuff.config.ts` | it doesn't load, or exports the wrong thing |
| Assets | the asset pipeline fails, or warns |
| `saves.json` | it isn't valid JSON |
| Agent files | `AGENTS.md`, `CLAUDE.md` or `.mcp.json` is missing |
| Agent skills | the project's skills are missing, or written for another debuff version |
| Browser | no Chromium-based browser for scenarios, fuzzing and the MCP server |
| Latest version | a newer debuff is out (from 0.21) |

Advice (`▲`) never fails the command: a missing `.mcp.json` or a newer release is worth knowing, not a reason to stop.

## What `--fix` does, and what it won't

`--fix` only does what can't lose your work:

- installs, dedupes, and adds `@debuffjp/dev` or TypeScript, with whichever package manager the project's lockfile says it uses (npm, pnpm, yarn or bun);
- writes `.mcp.json` when there isn't one;
- writes the project's agent skills for the installed debuff version.

It never overwrites a `.mcp.json` that exists, since it may list other servers, and it never changes the version of a package you already depend on. To move to a newer release, `npx debuff upgrade` does that deliberately (from 0.21).

## `--live` boots the game

Static checks can pass while the game still won't start. `npx debuff doctor --live` also starts the dev server, opens the game in the browser scenarios use, and waits for its dev hooks. If the game throws while starting, you get the error; if the hooks never appear, you get the line to add to `src/main.ts`.

## For agents

`npx debuff doctor --json` prints the checks as one JSON document, and the MCP server has a `doctor` tool that returns the same thing. debuff's other commands point here too: when one fails because of the setup it exits 2 and ends with `run npx debuff doctor`, so an agent knows to check the setup rather than retry. The full set of exit codes is in [What a coding agent needs from a CLI failure](/research/what-agents-need-from-cli-failures).

`doctor` exits 2 when a required check fails (1 before 0.20) and 0 otherwise.

Next time something won't start:

```bash
npx debuff doctor --fix
```