Semver's compatibility promise says a minor or patch bump should never break a consumer. In practice, why can upgrading within a caret or tilde range still break a build, and what upgrade-risk mitigations do teams actually rely on?

## What the version number claims Semantic versioning's core claim is that the version number itself carries a machine-readable compatibility contract: - increment the **patch** digit for a bug fix, - the **minor** digit for a backward-compatible addition, - and the **major** digit for anything that breaks existing callers. Range operators like caret and tilde, and their interval-notation equivalents, are built entirely on trusting that contract — a caret range assumes every minor and patch release under a given major is safe to auto-adopt, and a tilde range assumes only that patch releases are safe. ## Nobody enforces the contract The critical thing to understand is that this contract is enforced by nobody. No package registry — not npm, not Maven Central, not RubyGems — mechanically verifies that a version bump matches the actual scope of change before allowing a publish. The version number is whatever the maintainer typed, and semver compliance is a social convention that depends entirely on the publisher's discipline and judgment. ## Where breaking changes leak in That gap between promise and enforcement is where breaking changes leak into 'safe' ranges. 1. **The most common cause is human error:** a maintainer genuinely believes a change is backward-compatible and ships it as a minor or patch, but misses an edge case — a default value change, a stricter input validation that now rejects previously-accepted input, a changed error message that some downstream code was pattern-matching on, or a TypeScript type definition that got narrower and now fails to compile for consumers even though the JavaScript runtime behavior is identical. 2. **A second cause is transitive:** the package itself didn't change its public API, but one of its dependencies did, and that change surfaces through in a way the maintainer didn't anticipate or test for. 3. **A third, rarer but higher-stakes cause** is a compromised maintainer account or build pipeline publishing a malicious release under an innocuous-looking version bump — because nothing about the registry's versioning rules distinguishes a legitimate patch from a hostile one. ## A probabilistic bet, not a guarantee The practical consequence is that a range-based upgrade is a probabilistic bet, not a guarantee, and the probability of trouble scales with how wide the range is and how deep and unreviewed the dependency tree is. A tilde range narrows the bet to patch-only changes, which statistically carry far less risk of behavioral drift than minor releases that add or restructure functionality — but 'far less risk' is not 'zero risk,' since patch releases can still misfire. ## The mitigations teams actually rely on Because the contract itself can't be strengthened by the consumer, real mitigation happens downstream of it, in the consuming team's own process. 1. **The first and most load-bearing defense is test coverage:** a build that fails its test suite the moment a dependency upgrade changes behavior turns an invisible drift into a loud, immediate signal, which is why teams that rely heavily on floating ranges also tend to invest heavily in integration and contract tests around dependency boundaries. 2. **The second is gating the upgrade path itself** — rather than letting every install silently re-resolve ranges, teams use a lockfile plus an automated bot (Renovate, Dependabot) that proposes each version bump as its own reviewable, individually-tested pull request, so a single bad release is caught in CI on one PR rather than silently blending into a large, unreviewed batch of changes. 3. **The third is staged rollout** for dependencies that matter enough to justify it: canarying a new version to a subset of traffic or environments before promoting it everywhere, the same discipline applied to a team's own code deployments. 4. **The fourth is selective tightening:** for dependencies where a break would be especially costly — a payment SDK, a crypto library, a database driver — teams often deliberately abandon caret in favor of tilde or exact pins, accepting slower feature adoption in exchange for a smaller, fully human-reviewed set of changes. ## A concrete illustration A concrete illustration: a team runs a Node service depending on a logging library via a caret range. The library's maintainer ships what they believe is a minor release adding a new output format option, but a refactor accidentally changes the default timestamp format from ISO-8601 to a locale-dependent string. Nothing about the change looks breaking from the library's public function signatures, so the maintainer bumps the minor version and semver's letter is technically satisfied for anyone reading the changelog casually. - A team with no tests around log output and no reviewed-upgrade process picks this up silently on the next fresh install and only discovers it when a downstream log-parsing pipeline starts failing in production, days after the actual dependency change, with no corresponding commit in their own repository to point at. - A team with contract tests on its logging format, and an upgrade process that routes every dependency bump through a reviewed PR with CI, catches the exact same upstream mistake before it ever reaches production — the difference isn't the range they chose, it's the process wrapped around it.