Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm fails while preparing a dependency installed from git

Errornpm ERR! git dep preparation failed

Short answer

When npm installs a package from a git URL, it may have to build it first. If that package has a prepare or build script, npm installs its dependencies and devDependencies and runs the script, and any error there ends the install. Read the output above the message, then pin a working commit or use a published release.

  • Applies to npm 10, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Scroll up from the error. The lines before 'git dep preparation failed' hold the real failure from the dependency's own build.

    npm install 2>&1 | tail -n 60
  2. 2Match what you see, then jump to its fix

    1. 1Compiler, TypeScript or bundler errors printed just above the npm messageThe dependency's prepare or build script failsFix
    2. 2It worked last month; nothing changed on your sideNo ref given, so the default branch is installedFix

What does the error look like?

  • npm ERR! git dep preparation failed

Cause 1 of 2

The dependency's prepare or build script fails

1Check

npm treats a git dependency as needing a build when its package.json has workspaces or scripts such as build, prepare, prepack, preinstall, install or postinstall. With a prepare script it installs the dependency's devDependencies and runs the script before packaging.

grep -n -A8 "scripts" node_modules/my-lib/package.json

2Fix

Use a published release from the registry instead of the git URL if one exists. Otherwise fix the build problem the log shows (for example a Node.js version the package does not support).

npm uninstall my-lib
npm install my-lib@latest

3Verify

npm install finishes with no preparation error.

npm install && npm ls my-lib

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 2

No ref given, so the default branch is installed

1Check

Without #commit-ish or #semver:, npm installs the repository's default branch, so a new commit there can break the install.

grep -n "git" package.json

2Fix

Pin a commit or a semver tag in the dependency URL.

"dependencies": {
  "my-lib": "git+https://github.com/example/my-lib.git#semver:^1.2.0"
}

3Verify

Install from a clean node_modules.

rm -rf node_modules && npm install

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Prefer registry releases over git URLs for anything that needs a build.
  • Always pin a commit-ish or semver tag on git dependencies.
  • Commit the lockfile so every machine installs the same commit.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.