Skip to main content
Contentstack MCP profile hub is in general availability!

npm error code E401 on Launch: install private packages

5 min read

Your build fails before it compiles a single file. The deployment log stops in the dependency step with E401 and a message about a password, while npm install works fine on your laptop. Launch is trying to download a package from a private registry, and it has no credentials to do it with.

This happens with private packages on npmjs.com, GitHub Packages, Font Awesome Pro, Azure Artifacts, JFrog Artifactory and any other registry that requires a token.

What you'll learn

  • Why private package installs fail on Launch but not locally

  • How to write an .npmrc that's safe to commit

  • How to pass the token to the build with a Launch environment variable

  • What else to check when the token is set and the error stays

Symptoms

The deployment fails in the dependency installation step:

npm error code E401
npm error Incorrect or missing password.
npm error If you were trying to login, change your password, create an
npm error authentication token or enable two-factor authentication then
npm error that means you likely typed your password in incorrectly.
...
Installing dependencies failed
Deployment failed: Please try to redeploy the site, or contact support for assistance.

Variations you may see:

  • npm error code E401 with Unable to authenticate

  • npm error code E404 for a scoped package such as @your-org/ui, when the registry hides private packages from unauthenticated requests

  • npm warn deprecated lines just before the error. They are unrelated.

Why it happens

Launch concept: every Launch build runs on a clean build machine. It clones your repository, installs dependencies and builds. Nothing from your machine comes along.

Locally, npm authenticates with a token from your user-level ~/.npmrc, written there when you ran npm login or set it up for your company registry. That file isn't in the repository, so Launch never sees it. The build machine reads only the .npmrc in your project, and if that file points a scope at a private registry without a valid token, the registry answers 401. npm turns that into "Incorrect or missing password", but there is no password involved. It means the auth token is missing.

The other common version: a project .npmrc with a token that is hard-coded, expired or revoked. That is both a build failure and a leaked secret.

Fix it

Commit a token-free .npmrc

Put an .npmrc at the root of what Launch builds, with a placeholder instead of the token:

# .npmrc, safe to commit
@your-org:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

npm replaces ${NPM_TOKEN} with the environment variable of the same name when it runs. This is the standard npm pattern for private packages in CI.

For a scope on another registry, point the scope at it and add an auth line for that host:

@your-org:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=${FONTAWESOME_NPM_TOKEN}

Every registry host needs its own _authToken line. One valid token doesn't cover a second registry.

Set the token on the Launch environment

  1. Create a token with read-only access to the packages you need. On npmjs.com that is a granular or read-only access token. On GitHub Packages, a token with read:packages.

  2. In Launch, open the environment's Settings > Environment Variables.

  3. Add NPM_TOKEN (and any other names your .npmrc uses) with the token as the value. No quotes, no spaces around it.

  4. Save and trigger a new deployment.

Environment variables are per environment, so add the token to every environment that builds this project. Launch environment variable values are visible to everyone with access to the project. Use a read-only token scoped to the packages you need, not a personal token with publish rights.

Remove the committed token

If the .npmrc in your repository has a real token in it, replacing it with a placeholder isn't enough. The token is still in your Git history. Revoke it at the registry, create a new one, and set the new one on Launch.

Check that it worked

Reproduce the clean build machine locally before you push. Move your user config out of the way and install with only the project .npmrc:

NPM_TOKEN=<your-read-only-token> npm ci --userconfig /dev/null

If that succeeds, Launch will too. On Launch, the deployment log should move past the dependency step and print the build output. Read it with:

csdx launch:logs --environment production --deployment <deployment-uid> --type d

If the token is set and E401 stays

Work through these in order:

  • The variable name doesn't match. ${NPM_TOKEN} in .npmrc and NPM_TOKEN on Launch must match exactly, including case.

  • The token expired or was revoked. Granular tokens on npmjs.com and many company registries expire. Generate a new one and update the variable.

  • The token can't read that package. A token for one organization or scope doesn't grant access to another.

  • A second registry has no token. Search .npmrc for every //host/:_authToken= line and make sure each referenced variable is set.

  • The .npmrc isn't where Launch builds. In a monorepo, put it at the repository root next to the lockfile that the install uses.

  • The dependency is no longer needed. Starter templates and old forks sometimes carry a private registry for a package the current version no longer uses. Removing the dependency and the .npmrc entry is a valid fix.

Prevent it

  • Never commit a real token. Add a secret scanner or a pre-commit hook that rejects _authToken= followed by anything other than ${.

  • Keep the placeholder names in your .env.example so the next environment gets them too.

  • Use read-only tokens with an expiry date, and put the renewal in your calendar. A token expiring is the most common reason a build that worked last month fails today.

  • Run npm ci --userconfig /dev/null in your own CI so a missing token fails there first.

Key takeaways

  • npm error code E401 on Launch means a private registry rejected the install because there is no valid auth token.

  • Commit an .npmrc with //host/:_authToken=${NPM_TOKEN} and set NPM_TOKEN as a Launch environment variable.

  • Every registry host needs its own token line and variable.

  • Revoke any token that was ever committed, even after you remove it from the file.

  • Test with npm ci --userconfig /dev/null to reproduce the clean build machine locally.

Frequently asked questions

  • What password does npm E401 on Launch refer to?

    The auth token for a private npm registry. The Launch build machine has no npm login, so a registry that needs authentication rejects the install.

  • Why does npm install work on my machine but fail on Launch?

    Your machine has a cached login or token in your user-level ~/.npmrc. The Launch build machine starts clean and only sees the .npmrc in your repository.

  • Is it safe to commit .npmrc?

    Yes, as long as it only contains registry URLs and ${VARIABLE} placeholders. Never commit a file with a real token in it.

  • Do I need one token per registry?

    Each registry host in .npmrc needs its own _authToken line, and every variable those lines reference must be set on the Launch environment.