Why 1.2.4-beta does not satisfy ^1.2.3

^1.2.3 means "at least 1.2.3, below 2.0.0". The version 1.2.4-beta.1 is numerically inside that window, and npm will not install it. This is not a bug, and it is not arbitrary — but it is the semver rule people are least likely to have read, and it produces failures in both directions.

The rule

A version carrying a prerelease tag satisfies a range only if some comparator in the matching set names the same major, minor and patch, and carries a prerelease tag of its own.

1.2.4-beta  vs  ^1.2.3        → no match
  comparators are >=1.2.3 and <2.0.0
  >=1.2.3 has no prerelease → 1.2.4-beta is excluded

1.2.3-beta  vs  ^1.2.3-alpha  → match
  >=1.2.3-alpha is a prerelease of the same 1.2.3

The reasoning is about intent. Somebody who writes ^1.2.3 is asking for released versions of the 1.x line. A prerelease of 1.2.4 is an unfinished version of something they have not asked for, and installing it because it happens to sort between two numbers would be a surprise — the kind that appears in production rather than in a test run.

How to opt in deliberately

Name a prerelease of the version you want. ^1.2.3-0 allows every prerelease of 1.2.3 and everything above it, because -0 sorts below any other tag. That is the idiomatic way to say "including prereleases of this one".

• ^1.2.3 — released versions only, up to but not including 2.0.0.
• ^1.2.3-0 — the same window, plus prereleases of 1.2.3.
• >=1.2.3-0 <2.0.0-0 — the explicit form, when you want to be unambiguous.

The other caret surprise

Caret widens to the next major, except below 1.0.0, where the specification treats every release as potentially breaking. So the allowed window narrows as the version approaches zero, and three expressions that look alike behave very differently.

^1.2.3  →  >=1.2.3  <2.0.0     (the whole 1.x line)
^0.2.3  →  >=0.2.3  <0.3.0     (0.2.x only)
^0.0.3  →  >=0.0.3  <0.0.4     (that exact version)

This is why a dependency sitting at 0.x never updates on its own the way a 1.x one does, and why publishing 1.0.0 changes how every consumer receives your releases whether or not the code changed.

Ordering has its own corners. Numeric prerelease identifiers compare as numbers, so beta.11 comes after beta.2 rather than before it as a string sort would have it. A numeric identifier sorts below an alphanumeric one. Build metadata after a plus sign is ignored entirely when comparing, so 1.0.0+a and 1.0.0+b are the same version.

Where this actually bites

The usual sequence is a release candidate published to test an upgrade. The team writes ^1.2.3 in the manifest, expects 1.2.4-rc.1 to arrive, and gets 1.2.3 instead. The lockfile does not change, the install succeeds, and the tests pass against the old version — so the release candidate appears to work and is promoted on that evidence. Nothing in the output says the version under test was not the one intended.

The reverse happens on private registries that publish every commit as a prerelease. A range written without thinking about the rule quietly pins the team to the last released version for months, and the fix is assumed to be a registry or cache problem long before anybody suspects the range.

Both are cheap to check before they cost a day. The range and the version are two short strings, and the only question is whether one matches the other — which is the sort of thing worth answering directly rather than by running an install and reading a lockfile.