# Atlas NpmInstallFailedError: npm install failed while adding a package > Look at the `dir` field on NpmInstallFailedError and try the install there by hand to see the real npm output. Atlas raises NpmInstallFailedError because it installs npm packages on demand, for plugins and for provider SDKs declared via model.api.npm, and one of those installs failed. The tagged error carries `add`, the packages it tried to add, and `dir`, the directory it ran in. Check network access to the npm registry from the machine running Atlas, then look at the `dir` field and try the install there by hand to see the real npm output. ## Symptom Installing a plugin or a provider package in Atlas fails with NpmInstallFailedError, which carries the packages it tried to add and the directory it ran in. The package is not installed and the plugin or provider does not become available. ## Cause Atlas installs npm packages on demand, for plugins and for provider SDKs declared via model.api.npm. Any install failure is wrapped in the tagged NpmInstallFailedError with `add`, the package list, and `dir`, the directory the install ran in. ## Fix 1. Check network access to the npm registry from the machine running Atlas. 2. Look at the `dir` field on the error and try the install there by hand to see the real npm output. 3. Clear a corrupt cache or lockfile in that directory and retry. 4. If a provider package has no import entrypoint, you will instead see: Package has no import entrypoint. ## Why does Atlas run npm install at all Atlas installs npm packages on demand for 2 reasons: for plugins, and for provider SDKs declared via model.api.npm. When either install fails, Atlas wraps the failure in the tagged NpmInstallFailedError rather than letting a raw npm error escape into the agent loop. On-demand installation is why an NpmInstallFailedError can appear at moments you did not expect, such as the first time you select a model whose provider SDK is declared via model.api.npm. Atlas lets you switch the active model and provider on the fly with favorites and recents, and a provider whose SDK is not yet present triggers an install right then. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, and those plugins are the other trigger. Both paths land on the same tagged error when npm fails. ## How to fix NpmInstallFailedError in Atlas Fix NpmInstallFailedError by checking network access to the npm registry from the machine running Atlas first. A registry that is unreachable, proxied, or blocked by a firewall is the most direct explanation, and in 2026 it fails every on-demand install Atlas attempts, not just 1 package. Check registry reachability from the actual machine running Atlas, not from your laptop, because a container, a CI runner, or a remote dev box may sit behind different network rules. If the registry is reachable and the install still fails, move on to the per-directory diagnosis: the NpmInstallFailedError carries `dir`, and that directory is where the real npm output lives. Registry access is worth ruling out first only because it is fast to check and it explains a broad class of failures in one step. ## How to read the add and dir fields on NpmInstallFailedError The Atlas NpmInstallFailedError carries exactly 2 pieces of context: `add`, the packages it tried to add, and `dir`, the directory the install ran in. Read both before changing anything, because they tell you what npm was asked to do and where it was asked to do it. Look at the `dir` field on the error and try the install there by hand to see the real npm output. Atlas wraps the failure, so the tagged error is deliberately terse. Running the install yourself in that directory gives you npm's full, unfiltered diagnostic, which is where the actual cause is written. The `add` field tells you which packages were in play, which matters when a plugin pulls several at once and only one of them is failing. Together the two fields turn a wrapped error into a reproducible command. ## How to clear a corrupt npm cache or lockfile for Atlas Clear a corrupt cache or lockfile in the directory named by the `dir` field on the Atlas NpmInstallFailedError, then retry. A damaged lockfile in that 1 directory makes the same on-demand install fail identically on every attempt, no matter how healthy the npm registry is. Scope the cleanup to the directory the error names. Atlas runs the on-demand install in that directory, so a lockfile or cache problem elsewhere is irrelevant, and clearing state in the wrong place accomplishes nothing while risking collateral damage to your project. After clearing, retry the operation that triggered the install, whether that was loading a plugin or selecting a model whose provider SDK is declared via model.api.npm. A repeatable failure that survives a clean cache and a reachable registry needs the by-hand npm output to diagnose. ## What "Package has no import entrypoint" means in Atlas Atlas prints "Package has no import entrypoint" when a provider package installed successfully but exposes no import entrypoint for Atlas to load. It is a different error from NpmInstallFailedError, and the 2 have different fixes: here npm did its job, and the package itself is the problem. Distinguishing the two errors saves real effort. Clearing caches, checking registry access, and re-running npm by hand are all remedies for NpmInstallFailedError, and none of them help when the package simply has no import entrypoint. In that case the install already worked. The fix belongs on the package side, and the message names the package for you. Read which of the two errors Atlas actually raised before you start clearing lockfiles, because the two failures happen at different stages of the same on-demand install path. ## How to verify the Atlas npm install fix worked Verify the Atlas fix by retrying the action that triggered the install and confirming NpmInstallFailedError does not come back. Success means npm exits 0, adds every package listed in the error's `add` field inside the directory named in its `dir` field, and the plugin or provider loads. Retry the original action rather than only the by-hand npm command, because a manual install in the right directory proves npm can work there but does not prove the Atlas on-demand path now succeeds. If NpmInstallFailedError returns with the same `add` and `dir` values, nothing has changed and the by-hand npm output is your next read. If "Package has no import entrypoint" appears instead, the install itself now succeeds and you have moved on to a package-side problem. ## FAQ ### How do I fix NpmInstallFailedError in Atlas? Check network access to the npm registry from the machine running Atlas, then look at the `dir` field on the error and try the install there by hand to see the real npm output. ### What does NpmInstallFailedError carry in Atlas? The tagged NpmInstallFailedError carries `add`, the packages Atlas tried to add, and `dir`, the directory the install ran in. Both fields are needed to reproduce the failure by hand. ### Why is Atlas running npm install without me asking? Atlas installs npm packages on demand, for plugins and for provider SDKs declared via model.api.npm. Selecting a model whose provider SDK is not yet present triggers an install right then. ### How do I see the real npm error behind an Atlas install failure? Look at the `dir` field on NpmInstallFailedError and run the install by hand in that directory. Atlas wraps the failure, so the unfiltered npm output only appears when you run it yourself. ### Can a corrupt lockfile cause NpmInstallFailedError? Yes. Clear a corrupt cache or lockfile in the directory named by the `dir` field and retry. A damaged lockfile there makes the same on-demand install fail identically every time. ### What does "Package has no import entrypoint" mean in Atlas? "Package has no import entrypoint" means the provider package installed but exposes nothing for Atlas to import. The npm install succeeded, so the fix belongs on the package side, not the registry. ### Does Atlas need npm registry access to load plugins? Yes. Atlas installs plugin packages on demand from npm, so the machine running Atlas needs network access to the npm registry or the install fails with NpmInstallFailedError. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/npm-install-failed Source of truth: aeo_pages row `/resources/troubleshooting/npm-install-failed` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.