Technology · PRACTICAL GUIDE
npm ETARGET? Prove the registry, requested range and published versions first
“No matching version found” can come from a version that never existed, a tag or range mismatch, a scoped private registry, or stale mirror metadata. This evidence-first workflow locates the missing match before cache cleaning or lockfile deletion.
When npm reports ETARGET or “No matching version found,” preserve the exact package specification and test it against the registry npm actually used. The decisive evidence is the requester, registry endpoint, published version set and dist-tag mapping—not whether deleting a cache or lockfile happens to make the next install different.
Capture the exact package spec and requester
Copy the complete ETARGET line before changing files. Record the package name, the requested exact version, range or tag, the npm version, and whether the request came from package.json, package-lock.json, a workspace, a generated template or a transitive dependency. Search both manifests for the exact package string. If it is transitive, use the install log and dependency tree to identify the parent that asked for it. This first step prevents a top-level version edit from hiding the real requester.
Query the same registry npm is actually using
Run npm config get registry, then check any scope-specific registry in the project, user and CI npmrc files without printing tokens. Query the failing package against that exact endpoint with npm view <package> versions --json and npm view <package> dist-tags --json. npm resolves package names and versions through a registry, and scoped packages can use a different registry from unscoped packages. A version visible on npmjs.com does not prove that the configured private registry or mirror currently exposes it.
Separate an exact version, a range and a tag
An exact request such as 4.2.1 must be present as a published version. A range such as ^4.2.1 must match at least one version returned by the registry. A label such as latest, beta or next is a dist-tag that points to a version and can move independently of the version list. Compare the requested form with both versions and dist-tags instead of assuming the package's repository tag, the Node.js version or a GitHub release is an npm package version.
Check prerelease and publication boundaries
Semantic Versioning treats a prerelease such as 3.0.0-beta.9 as lower precedence than the normal 3.0.0 release; the two are not interchangeable identifiers. If the registry lists only a prerelease, an exact request for 3.0.0 still has no published match. Also check the package's publish times and dist-tags before changing the range: a template may request a version that was never published, was unpublished or was temporarily unavailable. Preserve the failing specification as evidence before choosing any substitute.
Audit the manifest, lockfile and mirror as separate layers
If npm view shows the requested version on the same registry, compare the command environment with the failing CI or IDE: registry URL, scope mapping, proxy and credentials may differ. Then locate the request in package.json and package-lock.json and identify whether it is direct or transitive. For a private proxy, compare its metadata with the upstream registry and use the repository administrator's supported refresh or cache invalidation path. Do not delete the lockfile or force-clean the local cache before you know which layer supplied the missing version.
Fix only the proven mismatch
If the version never existed, correct the template or dependency to a version supported by the project and test the resulting dependency change. If a dist-tag points somewhere unexpected, use an explicit verified version or wait for the publisher rather than guessing. If a private mirror is stale, refresh that mirror instead of weakening every project. If package metadata differs only in CI, align the scoped registry configuration without exposing credentials. Re-run npm view against the effective registry, then install and review the lockfile diff before accepting the repair.
