In an npm workspaces repo, `@rota/date-rules` was bumped to 2.0.0 while `@rota/ui` still declares `^1.0.0`; why does `npm install` now fail with E404?
answer
- the range is a condition
- link only when it matches
- otherwise ask the registry
- never-published name means 404
- re-save with -w, check link: true
basics
~20 snpm links a sibling workspace only when its local version satisfies the dependent's range. 2.0.0 is outside ^1.0.0, so npm asks the registry for @rota/date-rules, which was never published. Re-save the range with npm install @rota/date-rules -w @rota/ui.
solid answer
~40 snpm treats a dependency on a sibling like any other: the declared range must be satisfied. If the workspace's local version matches, npm links the folder; if not, it tries to resolve the range from the configured registry. `@rota/date-rules` is now `2.0.0`, which `^1.0.0` excludes, so npm asks the registry for a `1.x` version of a package that was never published and the install stops with `E404`. Had a matching version been published, it would be worse: the install succeeds and `@rota/ui` silently runs that old registry copy, nested under its own `node_modules`. Fix it by re-saving the range, `npm install @rota/date-rules -w @rota/ui`, which writes `^2.0.0`, then confirm in the root `package-lock.json` that the sibling's entry is a link, with `"link": true` and `resolved` pointing at `packages/date-rules`.
code
json · 11 lines{
"packages": {
"node_modules/@rota/date-rules": {
"resolved": "packages/date-rules",
"link": true
},
"packages/date-rules": {
"version": "2.0.0"
}
}
}go deeper
Remember that the range one workspace declares on another still has to match the sibling's local version for npm to link it.
Explain the fallback: no matching local version means npm resolves the range from the registry, failing with E404 if it was never published.
Diagnose the silent variant, an old registry copy nested under the dependent, from the lockfile, and fix it by re-saving the range with -w.
Set the team rule: bump sibling ranges with every major, review lockfile link entries, and scope internal names so the registry cannot answer instead.
## The rule: a workspace link must satisfy the range When one workspace depends on another in npm, the dependency is written as an **ordinary semver range**, such as `"@rota/date-rules": "^1.0.0"`; npm has no special workspace range syntax. During install, npm treats that line like any other dependency: it looks for a version that **satisfies the range**. The local workspace is the preferred candidate, but only on that condition: - if the sibling's **local version satisfies** the range, npm **links** the workspace folder; - if it **does not**, npm tries to satisfy the range **from the configured registry**, exactly as it would for a third-party package. Nothing warns you that the local package was passed over; npm just resolves the range. ## What happened here In the shift-rota repository: 1. `@rota/date-rules` gained a breaking change and its `package.json` was bumped to `"version": "2.0.0"`. 2. `packages/ui/package.json` still says `"@rota/date-rules": "^1.0.0"`, and a caret range on `1.0.0` stops below `2.0.0`. 3. `npm install` therefore cannot link the local workspace and asks the registry for a `1.x` version of `@rota/date-rules`. 4. The package was never published, so the registry answers with a 404 and the install stops with **`E404`**: the requested package could not be found, or you do not have permission to access it. The glob in the root `workspaces` field is fine, and so is the folder; the dependent's range is what changed meaning. ## The quieter failure: a matching registry version The 404 is the lucky outcome. Had a `1.x` version of `@rota/date-rules` ever been published, the install would **succeed**: npm installs that registry copy nested under `packages/ui/node_modules/@rota/date-rules`, and `@rota/ui` silently runs old code while everyone edits `packages/date-rules`. And for an unscoped name, an unrelated public package with the same name could be pulled in, which is why internal packages are usually scoped. | Local workspace version | Registry has a match? | Outcome | |---|---|---| | satisfies the range | irrelevant | linked to the workspace folder | | does not satisfy | no | install fails with `E404` | | does not satisfy | yes | registry copy installed, nested, old code runs | ## Fixing and verifying Re-save the dependent's range against the current local version: ```bash npm install @rota/date-rules -w @rota/ui npm ls @rota/date-rules ``` The first command detects the workspace and writes a range for its current version, `^2.0.0`; editing the line by hand and running `npm install` works too. Then confirm in the root `package-lock.json` that the sibling is linked rather than downloaded: ```json "node_modules/@rota/date-rules": { "resolved": "packages/date-rules", "link": true } ``` A **link entry** has `"link": true` and a `resolved` value pointing at the workspace folder. A registry copy instead appears under a path such as `packages/ui/node_modules/@rota/date-rules`, with a registry tarball URL in `resolved` and an `integrity` hash. Deleting the lockfile and reinstalling changes nothing here, because the range is still unsatisfied. ## Why npm behaves this way A workspace dependency is not a special kind of dependency in npm; it is an ordinary dependency for which a local candidate happens to exist. That design keeps the manifest meaningful in both places it is read: - **Inside the repository**, the range decides whether the local folder is acceptable, so a dependent that was written against the 1.x API is never silently wired to an incompatible 2.0.0. - **After publishing**, the same line is what a consumer's install resolves from the registry, so what was tested together locally is described by the ranges that ship. The cost is the trap in this question: a version bump in one workspace changes what its dependents' ranges mean, and npm reports it only as a registry lookup that failed, or not at all. ## Keeping ranges honest - **Bump dependents with the dependency.** When a workspace takes a new major version, update every sibling's range in the same change and run the root install. - **Watch `0.x` versions.** A caret on a `0.x` version, such as `^0.3.0`, does not admit `0.4.0`, so even a minor bump of an early package can break the link. - **Read the lockfile diff.** A workspace entry turning from a link into a nested registry copy is the signal, and it shows up in review before anything ships. - **Prefer scoped names for internal packages.** A scope you control removes the chance that the registry answers with somebody else's package. The range between siblings is not decoration: it is the condition under which npm uses the code in the repository at all.
- What would have happened if version 1.4.0 of `@rota/date-rules` existed on the registry?The install would succeed. npm would satisfy `^1.0.0` with the registry's 1.4.0, nested under `packages/ui/node_modules`, and `@rota/ui` would run that published code while the team edits the local 2.0.0. Only the lockfile diff, or `npm ls @rota/date-rules`, would show it.
- How do you tell from the root package-lock.json whether a sibling is linked?A linked workspace has an entry under `node_modules/<name>` with `"link": true` and `resolved` set to the workspace folder. A registry copy has a tarball URL in `resolved` and an `integrity` hash instead, usually at a nested path under the dependent workspace.
- Why can a minor bump from 0.3.0 to 0.4.0 break the link too?A caret range on a `0.x` version, such as `^0.3.0`, does not admit `0.4.0`, so the local version stops satisfying it and npm falls back to the registry, exactly as with the major bump. Re-save the range whenever an early package moves its minor.
- npm always links a sibling workspace, whatever range the dependent declares.
- The E404 means the workspaces glob no longer matches packages/date-rules.
- Deleting package-lock.json and reinstalling makes npm link the local 2.0.0.
- A successful install proves @rota/ui runs the local date-rules code.
- npm rewrites a dependent's range by itself when a sibling's version changes.