TL;DR: Something in your Gemfile or its transitive dependencies pins rails to a range that excludes the version you want. Read the error output to name the blocking gems, then bundle update those blockers together with rails so Bundler can find one consistent set. Loosen the pin in your Gemfile only if the blocker has no newer release that supports your rails version.

## The error

```text
"bundle update failed: Bundler could not find compatible versions for gem \"rails\""
```

## Steps to fix

1. Run bundle install and read the full conflict section: it prints In Gemfile: rails (= X) and then each gem that depends on rails with its required range.
   Expected: You can name the blockers, for example old_gem was resolved to 1.0 which depends on rails below 7.0.

2. Check whether the blockers have newer releases supporting your rails version: bundle outdated old_gem or check rubygems.
   Expected: You learn whether an upgrade path exists or the blocker is abandoned.

3. Update rails and the blockers together: bundle lock --update=rails old_gem (use bundle update rails old_gem on older Bundler).
   Expected: Bundler prints Fetching gem metadata and resolves a consistent set, or names the next blocker to address.

4. Repeat for any further blockers, then run bundle install and bundle check.
   Expected: bundle check prints The Gemfile's dependencies are satisfied.

5. Run your test suite.
   Expected: Tests pass, confirming the resolved combination actually works together.

## Use this when

- bundle install or bundle update fails with could not find compatible versions for gem rails
- A rails major upgrade is blocked and you need to find which gems pin the old rails
- An agent's upgrade PR died in Bundler resolution and you need the manual procedure

## Not for this skill when

- Native extension build failures (gem install compiling C code), which happen after resolution
- Bundler version or lockfile format errors
- Ruby version incompatibilities reported as a ruby version mismatch rather than a gem conflict

## Variant phrasings

- Bundler could not find compatible versions for gem actionpack
- bundle update rails fails with dependency conflict
- In Gemfile rails was resolved to X which depends on Y

## Why it happens

Bundler resolves the entire gem graph at once, and rails is a meta-gem whose components (actionpack, activerecord, and the rest) must all share one version. Any gem that declares a dependency like rails below 7 vetoes every rails 7 candidate. Bundler reports the conflict instead of silently picking a broken mix, so the output is the diagnosis: the named blockers are the whole story.

## Edge cases

- Updating one blocker at a time can loop; update rails and all its blockers in a single bundle lock --update command.
- Some gems never released rails-7-compatible versions; then you either stay on rails 6, replace the gem, or fork it.
- After resolving, delete any stale vendor/cache gems or the old resolution can shadow the new one.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0TNApbOxPX9OYyrQjFFXjA