npm dependency errors in Bolt.new: causes and fixes

Most npm errors in a Bolt.new project come from four things: packages whose versions don't agree with each other (ERESOLVE), a package that needs native code the in-browser runtime can't run, a package or version that doesn't exist, or a lockfile that no longer matches package.json. Read the first error line, fix the version or swap the package, then reinstall from the Bolt terminal. Forcing the install with flags hides the problem rather than fixing it.

This guide shows where the errors appear, what each common message means, the fix for each one and a few habits that keep dependencies from drifting as the AI adds packages.

Where do npm errors show up in Bolt?

Bolt runs your project inside StackBlitz WebContainers, a Node.js environment that runs in your browser. Install and startup errors appear in three places:

• The preview, often as an error overlay or a page that never loads.
• The Bolt tab of the terminal in Code view, where Bolt runs its own install and dev commands.
• The Publish Output tab, when the error only happens during the production build.

Copy the error from the terminal rather than from the overlay. The terminal has the full message and the package names.

What does each error mean?

How do I fix a peer dependency conflict?

The error message names the two sides. It usually reads like "package A needs React 18, but the project has React 19".

1. Find who wants what. In the Bolt terminal:

   npm ls react
   npm view <package-a> peerDependencies

2. Move the outlier. Usually one package is behind. Check whether a newer version supports your setup (npm view <package-a> versions), install it, and retest. If no version supports it, replace the package.
3. Reinstall cleanly. StackBlitz's WebContainer troubleshooting suggests deleting package-lock.json, running npm install again and saving the project.

4. Use the escape hatches last. npm install --legacy-peer-deps or --force gets past the error, and StackBlitz may retry with --legacy-peer-deps automatically. Both leave mismatched versions in place, which can fail later at runtime or on another host. If you need to pin a nested dependency, the overrides field in package.json does it in one visible place:

   {
    "overrides": {
      "some-library": {
        "react": "$react"
      }
    }
   }

Why does a package work on my computer but not in Bolt?

Because some packages ship compiled native code (C or C++ built for your operating system), and WebContainers can't load it. You'll see Cannot load native addon because loading addons is disabled. Password hashing libraries, some image processors and local database drivers are typical examples.

The fix is an alternative written in JavaScript or compiled to WebAssembly: for example, bcryptjs instead of bcrypt. Often the better answer is not to need the package in the browser project at all: let your auth provider hash passwords, and do heavy image work in a server function or a storage service.

What if the AI installed a package that doesn't exist?

AI tools sometimes invent plausible package names. npm answers with a 404 and the install stops. Remove the package from package.json and ask Bolt which real library it meant.

Be more careful when the name does exist but you've never heard of it. Attackers register packages under names that AI tools tend to invent. Before keeping an unfamiliar package, look it up on npmjs.com: check that it has a linked source repository, recent releases and real download numbers. If any of that is missing, ask for a well-known alternative.

What about code written for the wrong version?

This one doesn't throw an install error. The package installs fine, but the AI wrote code for a different major version, so functions are missing or configuration is ignored. Libraries that changed how they're set up between majors, such as Tailwind CSS, routers and auth SDKs, are the usual suspects.

Check the installed version with npm ls <package>, then tell Bolt in the prompt: "The project uses Tailwind CSS 3.4; write code for that version." Better still, record key versions in Project settings > Knowledge so you don't have to repeat them.

How do I keep dependencies from drifting?

• Keep the lockfile. package-lock.json is what makes every install identical. Don't delete it as a routine fix, and make sure it's committed to GitHub.
• Upgrade on purpose. Run npm outdated once a month, upgrade one major version at a time, and test after each one.
• Clean up. npx depcheck lists packages nothing imports anymore, and npm dedupe removes duplicate copies. Fewer packages also means less for Bolt to read.
• Be careful with npm audit fix --force. It can jump to breaking major versions. Read the report and upgrade the flagged packages deliberately instead.
• Build before you publish. npm run build in the terminal surfaces errors that the dev server tolerates. Our guide to Bolt.new deploys failing on Netlify covers what happens when it's skipped, and TypeScript errors that break the build covers the other common blocker.

Quick answers

Is --legacy-peer-deps safe? It's a shortcut, not a fix. It installs mismatched versions that may break at runtime. Use it to unblock, then align the versions.

Should I delete node_modules and start over? It helps with corrupted installs, but it won't solve a version conflict. The conflict is in package.json.

Why do errors appear only when I publish? The production build is stricter than the dev server and runs the type checker and bundler over every file.

Can I run the project locally to avoid WebContainer limits? Yes. On your own computer native packages install normally; see running a Bolt project locally. Keep in mind the Bolt preview will still fail on them.

Dependencies tangled beyond a quick fix?

When conflicts keep coming back, the dependency tree usually needs one deliberate cleanup. Our Bolt app rescue starts with a code review and a fixed price for each fix, and ongoing maintenance keeps upgrades on schedule. Start with the free health check, or send us the error.