Introduction

When Bundler cannot find compatible gem versions from a configured source, it halts dependency resolution with a clear but sometimes misleading error. This commonly occurs with private gem servers, removed gem versions, or network authentication failures.

Symptoms

  • Could not find gem 'my-private-gem' in rubygems repository https://rubygems.org/
  • Bundler::Fetcher::AuthenticationRequiredError during bundle install
  • Could not find gems matching 'rails (= 7.1.3.2)' valid resolutions
  • Works locally but fails in CI/CD pipeline
  • bundle install times out after 30 seconds on gem fetch

Example error: `` Fetching gem metadata from https://rubygems.org/.......... Fetching https://github.com/company/internal-gem.git Could not find gem 'internal-gem (~> 2.0)' in https://github.com/company/internal-gem.git (at main@abc1234). Source contains 'internal-gem' at: 1.5.0, 1.6.0

Common Causes

  • Private gem server credentials expired or rotated
  • Git-based gems point to deleted branches or changed commit SHAs
  • Gem version was yanked from rubygems.org
  • Network proxy blocking gem source access
  • Gemfile.lock references a version no longer available

Step-by-Step Fix

  1. 1.Clear Bundler cache and retry:
  2. 2.```bash
  3. 3.bundle clean --force
  4. 4.rm -rf vendor/cache
  5. 5.bundle cache --all-platforms
  6. 6.bundle install
  7. 7.`
  8. 8.Verify gem source accessibility:
  9. 9.```bash
  10. 10.curl -I https://rubygems.org/api/v1/gems/rails.json
  11. 11.# For private sources:
  12. 12.curl -u username:password -I https://gems.company.com/api/v1/gems/internal-gem.json
  13. 13.`
  14. 14.Check if the gem version was yanked:
  15. 15.```bash
  16. 16.gem list rails --remote --all | grep "7.1"
  17. 17.# Or check the rubygems.org API
  18. 18.curl https://rubygems.org/api/v1/versions/rails.json | jq '.[].number'
  19. 19.`
  20. 20.Update the Gemfile to use an available version:
  21. 21.```ruby
  22. 22.# Before
  23. 23.gem 'rails', '7.1.3.2'

# After - use a version that exists gem 'rails', '~> 7.1.3' ```

  1. 1.For git-based gems, pin to a specific tag or commit:
  2. 2.```ruby
  3. 3.# Before
  4. 4.gem 'internal-gem', git: 'https://github.com/company/internal-gem.git', branch: 'main'

# After - pin to a specific commit SHA gem 'internal-gem', git: 'https://github.com/company/internal-gem.git', ref: 'abc1234def' ```

  1. 1.Reset Bundler source configuration:
  2. 2.```bash
  3. 3.bundle config unset gems.company.com
  4. 4.bundle config set gems.company.com username:password
  5. 5.bundle install
  6. 6.`

Prevention

  • Use version ranges (~>) instead of exact pins for public gems
  • Mirror private gem servers locally when possible
  • Add health checks for private gem sources in CI
  • Keep Gemfile.lock committed and review changes during PR
  • Use bundle config set --local for per-project credentials