​
🔧 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
mkdir -p ~/Projects
# Replace my-app with your folder name
mv ~/Desktop/my-app ~/Projects/
cd ~/Projects/my-app
  1. Clean dependencies and reinstall
rm -rf node_modules package-lock.json
npm cache verify
nvm use || true
npm install --legacy-peer-deps
  1. Start the dev server again
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)
rm -rf node_modules package-lock.json
npm cache verify
npm install --legacy-peer-deps
  1. Pin React 19 across the tree via npm overrides
Add to your package.json (top-level): 
{
  "overrides": {
    "react": "19.x",
    "react-dom": "19.x"
  }
}
Then reinstall: 
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
  1. Verify
npm run build
npm run dev
If warnings persist, ensure there are no duplicate React versions: 
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
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.