Troubleshooting Installation for Hugeicons Pro

Use this page when installing a Hugeicons Pro package fails with a 404, 401 or config error. It assumes you’ve followed Activate License. If something below points to a setup step, fix it there.

`404 Not Found` from registry.npmjs.org


npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@hugeicons-pro%2Fcore-stroke-rounded - Not found
npm ERR! 404 '@hugeicons-pro/core-stroke-rounded@*' is not in this registry.

Your package manager is looking on npmjs.org instead of the Hugeicons registry. Check that:

The config file from Add the Registry Config is in the project root, next to package.json.
The package name starts with @hugeicons-pro/, not @hugeicons/.
In .npmrc, both lines are present, each on its own line, with no extra spaces or quotes.
In CI and Docker, the config file is included in the build context and not excluded by .dockerignore.
With pnpm, the registry line is in a file. pnpm ignores the npm_config_@hugeicons-pro:registry environment variable, so setting it that way silently falls back to npmjs.org.

Then check which registry npm actually uses:


npm config get @hugeicons-pro:registry

It should print https://npm.hugeicons.com/. If it doesn’t, a user-level or global .npmrc is overriding yours. npm merges configs in this order: project → user → global → built-in. Run npm config list to find the conflicting file, or remove a global override with:


npm config delete @hugeicons-pro:registry

`401` immediately after setting up the config file

When HUGEICONS_LICENSE_KEY isn’t set, npm sends the unresolved placeholder as the token and the registry rejects it. Current npm versions do not tell you the variable is missing. You get a plain 401:


npm error code E401
npm error Unable to authenticate, your authentication token seems to be invalid.

So a 401 on a fresh setup almost always means the variable, not the key. Check in this order:

Locally: the variable has to be exported in the same terminal you install from. See “But I did set the variable” just below. It covers the four ways this goes wrong.
On Vercel, Netlify or CI: the variable is missing, or it isn’t exposed at build time. See Set the variable on your platform.
Using pnpm 10 or later: pnpm ignores the token line in a project .npmrc, locally and in deployments. See pnpm ignores the placeholder below.
Trailing whitespace: if you pasted the key into a CI secret field and picked up a newline, the error is different: Bearer … is not a legal HTTP header value. Re-paste without the line break.

”But I did set the variable”

Almost always, the export didn’t reach the shell that ran the install. Run this in the same terminal window and tab you install from:


printenv | grep -i hugeicons

Don’t check with echo $HUGEICONS_LICENSE_KEY. A misspelled name prints a blank line rather than an error, so echo $HUGEICONS_LICENSE_KEYS looks like it worked if that misspelled variable happens to exist. printenv | grep lists the names that are really set, so a typo is visible.

If the name you need isn’t in that list, one of these five is why.

You exported it in a different terminal. export only affects the shell you typed it into. Setting it in Terminal.app or iTerm does nothing for the integrated terminal in VS Code, Cursor or WebStorm, and the other way round. Every tab is its own process, and the value is gone when you close it. To set it once for every terminal, put the export line in ~/.zshrc or ~/.bashrc and open a new one.

The variable name doesn’t match. The name in your config file and the name you export have to be identical, character for character:


# .npmrc reads this name …
//npm.hugeicons.com/:_authToken=${HUGEICONS_LICENSE_KEY}
 
# … so this is the name you have to export.
export HUGEICONS_LICENSE_KEY="your-universal-license-key"

A different name, such as HUGEICONS_NPM_TOKEN, NPM_TOKEN, HUGEICONS_KEY or a stray plural like HUGEICONS_LICENSE_KEYS, is simply never read, and npm reports it as a 401 rather than as a missing variable.

You set it without export. Without export, the value belongs to your shell alone and is not passed to the programs it starts, so npm never receives it. echo still prints it, which makes this one easy to miss:


HUGEICONS_LICENSE_KEY="…"          # echo works, npm fails with 401
export HUGEICONS_LICENSE_KEY="…"   # npm works

You have an .envrc but not direnv. An .envrc file does nothing on its own. It needs direnv installed, hooked into your shell, and direnv allow run once in the project. Check with command -v direnv. Without it, load the file by hand:


set -a; source .envrc; set +a

You put it in .env. npm, pnpm and Yarn never read .env files. Only Bun does. See Set the variable locally.

Older npm 6 and 7 releases reported this as Failed to replace env in config: ${HUGEICONS_LICENSE_KEY}. If you see that message, the cause is the same: the variable isn’t set.

pnpm ignores the placeholder

pnpm 10 and later don’t use the token line from a project .npmrc. Depending on the version, the failure looks like this:


# pnpm 10
[WARN] Ignored project-level auth setting "//npm.hugeicons.com/:_authToken" in ".npmrc"
 ERR_PNPM_FETCH_401  GET https://npm.hugeicons.com/@hugeicons-pro%2Fcore-stroke-rounded

# pnpm 12
✗ Lockfile failed supply-chain policy check
Error: ERR_PNPM_META_FETCH_FAIL
  ╰─▶ ERR_PNPM_RESOLVING_NPM_RESOLVER_NETWORK_ERROR: Failed to fetch metadata
      from https://npm.hugeicons.com/@hugeicons-pro%2Fcore-stroke-rounded:
      HTTP status client error (401 Unauthorized)

pnpm does this on purpose: a committed file shouldn’t be able to send your secrets to a registry. Keep both lines in .npmrc (pnpm 9 still uses them), and give pnpm 10+ the token another way:

Locally: run this once.


pnpm config set "//npm.hugeicons.com/:_authToken" "$HUGEICONS_LICENSE_KEY"

Deployments: use the install command from pnpm 10 or later. On Coolify or Railpack, setting RAILPACK_INSTALL_CMD=pnpm install isn’t enough, because it doesn’t pass the token.

If the key is also missing, pnpm may ignore the whole .npmrc and look for the package on npmjs.org, so you get a 404 from registry.npmjs.org instead of a 401.

`401 Unauthorized` or `403 Forbidden` with the variable set

If printenv HUGEICONS_LICENSE_KEY prints your key and the install still fails, the registry is rejecting the key itself.

Confirm the registry accepts it:
```
npm whoami --registry=https://npm.hugeicons.com
```
A valid key prints a username. An invalid or missing one fails with ENEEDAUTH. The username it prints is a shared registry account, so it confirms the key works but not which key you’re using.
Copy the key again from the Tokens tab and update HUGEICONS_LICENSE_KEY everywhere it’s set.
Make sure your subscription is active. Yearly plans lose registry access when they expire.

Stale caches and lockfiles

A cached install or an old lockfile can keep failing after you fix the config.


npm cache clean --force
rm -rf node_modules package-lock.json
npm install

On CI and hosting platforms, clear the build cache and redeploy. On Vercel, use Redeploy without the existing build cache.

Known issues

Old npm versions: some npm 7.x releases ignore scoped registries. Upgrade npm:


npm install -g npm@latest

Yarn 2+ ignores .npmrc completely, everywhere, not just on Netlify. It only reads .yarnrc.yml. Use the config from the Yarn 2+ tab. Yarn 1 does read .npmrc.

GitHub Actions setup-node: setting registry-url writes its own .npmrc, which can override yours. Leave it out, as in the GitHub Actions example.

Need help?

If you’re still stuck, head to our Discord for help:

Join the Hugeicons Support Server

Please include:

Your config file (.npmrc, .yarnrc.yml or bunfig.toml), with the key removed
The full error message
Your platform (local, Vercel, Netlify, Docker, …)