> ## Documentation Index
> Fetch the complete documentation index at: https://blueprint.codeandcreed.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Common issues when building products with Kaizen

## 🔧 Troubleshooting

If you find yourself stuck on strange error/behaviors, it's worth checking out this list of common problems and fixes. You might just save yourself a few hours of debugging.

### 🐢 Dev server hangs on macOS (Desktop/iCloud)

Symptoms:

* `npm run dev` hangs at “starting…” or never shows logs
* Hot reload doesn’t trigger or is extremely slow

Root cause:

* Projects inside `~/Desktop` are often synced by iCloud and indexed by Spotlight
* Vite/React Router file watchers get interrupted (EINTR), breaking the dev server

Fix:

1. Move your repo out of Desktop/iCloud, e.g. to `~/Projects`

```bash theme={null}
mkdir -p ~/Projects
# Replace my-app with your folder name
mv ~/Desktop/my-app ~/Projects/
cd ~/Projects/my-app
```

2. Clean dependencies and reinstall

```bash theme={null}
rm -rf node_modules package-lock.json
npm cache verify
nvm use || true
npm install --legacy-peer-deps
```

3. Start the dev server again

```bash theme={null}
npm run dev
```

Notes:

* Do not keep active repos under `~/Desktop` or other iCloud-synced locations
* If you still see odd hangs, reboot once to clear stale file watcher handles

### ⚛️ React 18 vs 19 dependency mismatches (warnings, odd behavior)

Symptoms:

* Lots of npm peer dependency warnings
* Some libraries (e.g., UI/Checkout) expect React 18 while the project uses React 19

Fix options:

1. Clean and reinstall (often enough after moving directories)

```bash theme={null}
rm -rf node_modules package-lock.json
npm cache verify
npm install --legacy-peer-deps
```

2. Pin React 19 across the tree via npm overrides

Add to your `package.json` (top-level):

```json theme={null}
{
  "overrides": {
    "react": "19.x",
    "react-dom": "19.x"
  }
}
```

Then reinstall:

```bash theme={null}
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
```

3. Verify

```bash theme={null}
npm run build
npm run dev
```

If warnings persist, ensure there are no duplicate React versions:

```bash theme={null}
npm ls react react-dom | cat
```

You should see a single version of `react` and `react-dom` resolved.

### 🧭 React Router: failed to load in `virtual:react-router/server-build` after adding a route

Symptoms:

* Browser overlay or terminal shows:

```
Failed to load url /app/routes/blah-blah.tsx (resolved id: /app/routes/blah-blah.tsx) in virtual:react-router/server-build. Does the file exist?
```

Root cause:

* After creating/renaming a route file, Vite's module graph can get stale and the React Router virtual server build doesn't pick up the new file until a restart.

Fix:

1. Stop the dev server
2. Start it again

```bash theme={null}
npm run dev
```

Also check:

* The file actually exists at that path and is saved
* Path and filename casing match your OS and route config
* If you recently renamed/moved files, a restart clears the stale graph; if it persists, try removing `.vite` cache by restarting or a clean install

Verify:

* Reload the page; the route should resolve without the error

Refs (similar reports/notes):

* GitHub discussion confirms restart fixes it: `https://github.com/remix-run/react-router/discussions/13385`
* Related: `https://www.reddit.com/r/reactjs/comments/1k4rbpa/react_router_7_failed_to_load_url_types/`
* Similar underlying cause (Remix): `https://stackoverflow.com/questions/79115905/internal-server-error-failed-to-load-url-in-virtualremix-server-build-does-th`
* Vite HMR flakiness context: `https://github.com/vitejs/vite/issues/18217`

***

Still stuck? Open an issue with your environment details and any relevant context in the #ask-for-help channel in the Discord Server.