# Troubleshooting

> Fixes for common problems with the runtime, previews, npm, Git, saving and the Agent.

Last updated: October 17, 2026
Source: https://codevre.com/docs/ide/troubleshooting

## The runtime

**"The Codevre runtime failed to start."** The terminal, npm and previews need the runtime. Reload the page. If it keeps failing:

- Make sure `preview.codevre.dev` isn't blocked by an extension, a firewall or a school filter.
- Try a Chromium-based browser and turn off strict privacy extensions for codevre.com.
- Private/incognito windows can limit storage; try a normal window.

**The status bar says "booting…" for a long time.** The first start downloads the runtime. Later starts use the cache.

**"The runtime restarted because you signed in or out."** This is expected. Signing in or out, and connecting or disconnecting GitHub, restart the runtime so no credential carries over. Your files are restored, and `npm install` runs again if needed.

## Previews

**localhost:codevre is blank.**

- Is there an HTML file? Run `vre run index.html` or **Terminal ▸ Run Preview (VRE)**.
- Check `vre.settings.root`. If it points at a folder that doesn't exist, the status bar says *VRE root "X" has no files*. Fix or remove it in `.codevre/settings.json` and your User settings.
- Open DevTools (Console) for errors.

**The preview doesn't update when I save.** Check `vre.preview.autoRun` is `true`, and that the file isn't matched by `vre.settings.ignoreFiles`. The preview only auto-reruns once it's running.

**The preview reruns before my build finishes.** Set `"vre.preview.autoRun": false` in the project and have your build call `vre run` or `vre reload` when output is ready.

**A server started but no tab opened.** Make sure it's listening on a port, and check the terminal output. Type `localhost:PORT` in the Browser's URL bar.

**An external website stays blank in the Browser.** Many sites refuse to load in frames. Use **Open in new tab**.

## npm and Node

**An install fails with node-gyp, prebuild or binary errors.** The package needs native code, which can't run in a browser. Use a pure-JS alternative:

| Instead of | Try |
|---|---|
| `bcrypt` | `bcryptjs` |
| `sqlite3`, `better-sqlite3` | `sql.js`, or JSON files |
| `sharp` | Canvas in the browser, or `jimp` |
| `puppeteer`, `playwright` | Not available. Test in the preview |

**"Dynamic require of "./x.js" is not supported"** in an esbuild bundle means an import path is wrong. esbuild in Nodepod treats imports it can't resolve as external. Fix the path.

**`node_modules` vanished.** It's never saved to Codevre. It's reinstalled when the project opens, or run `npm install`.

See [What works in Nodepod](nodepod.md).

## Saving

**I can't save.** Sign in first. Saving to Codevre needs an account.

**"… is still downloading."** The project is still opening. Wait until the file has arrived before renaming, moving or deleting it.

**"… was saved from somewhere else since you opened it."** Another tab or device saved this project after you opened it. **Overwrite** replaces that version with yours. To keep it, cancel and reopen the project (your unsaved changes here would be lost; copy them first).

**"This project has N files — too many to save."** A project's file list has to fit in about 1 MB. Delete or exclude generated folders (build output, downloaded assets) and save again. Nothing was changed.

**"Saving is taking a while."** A large file is uploading slowly. Keep waiting, or skip it; it keeps its previous saved copy and uploads next time.

**"You've reached your Codevre IDE project limit."** Delete a project in the Projects tool, or upgrade your plan.

**Settings changes don't apply.** A syntax error in `.codevre/settings.json` keeps the last valid settings. Comments and trailing commas are fine; check for missing quotes or braces.

## Git and GitHub

**"Connect GitHub to push to GitHub."** Connect GitHub from Source Control or the terminal. See [GitHub](github.md).

**A push from a script or the Agent isn't authenticated.** This is by design. Push from Source Control, or type the `git push` yourself.

**Push rejected, or Sync keeps showing ↑1.** GitHub has commits you don't. Pull first, or confirm Force Push. If the branch was pushed from another device first, a one-time force push lines up the histories.

**My build output got committed.** Nodepod's Git doesn't support `.gitignore`. Unstage those files, and stage selectively.

## The Agent

**"Sign in to use the AI agent."** The Agent needs an account and your own API key. See [Providers and API keys](providers-and-keys.md).

**The provider rejected my key.** It may be invalid, disabled or out of credit. Paste a working key in the card and click **Save and retry**.

**"This model can't use tools."** Pick a model that supports tool calling, or switch to Chat.

**Free models keep failing.** They're rate-limited and change often. Codevre retries 3 times; after that, pick another model.

**The Agent paused at a checkpoint.** It hit its per-message budget. Read the summary and click **Continue**.

## Reporting a problem

Ask on [Discord](https://discord.gg/PpUWRvXjRg). These console helpers produce useful details to paste into your report:

| Helper | For |
|---|---|
| `await __scm.diagnose()` | Source Control and sync problems |
| `await __git.debugState()` | Git markers and repository state |
| `console.table(await __projects.debugStatus())` | Saving and project status |
| `__statusbars.debug()` | Problems counts and diff state |
| `cvtDebug()` | Terminal display |
| `CodevreAI.usageSummary()` | Agent turns, tokens and tool failures |

Open the console with F12, or Ctrl+Shift+J (Cmd+Option+J on Mac).