skip to content

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?

level: seniorimportance: nice to knowfreq 7%

answer

  1. the range is a condition
  2. link only when it matches
  3. otherwise ask the registry
  4. never-published name means 404
  5. re-save with -w, check link: true

basics

~20 s

npm 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 s

npm 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
json
{
  "packages": {
    "node_modules/@rota/date-rules": {
      "resolved": "packages/date-rules",
      "link": true
    },
    "packages/date-rules": {
      "version": "2.0.0"
    }
  }
}

go deeper

for a junior

Remember that the range one workspace declares on another still has to match the sibling's local version for npm to link it.

for a middle

Explain the fallback: no matching local version means npm resolves the range from the registry, failing with E404 if it was never published.

for a senior

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.

for a principal

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.