The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Most Rails bundle install failures on Ubuntu have a specific cause: missing compiler or development headers, incompatible dependency requirements, the wrong Ruby or Bundler version, a broken TLS/CA setup, or an incorrect deployment path or permission. Start by preserving the complete error and checking the active Ruby, Bundler, lockfile, and Bundler configuration. Then make the smallest change that addresses the diagnosed cause.
What bundle install is actually doing
Bundler installs the dependency set declared in your Rails application’s Gemfile. When Gemfile.lock is present and the Gemfile has not changed, Bundler normally installs the versions recorded in that lockfile instead of resolving an entirely new set. This is why the lockfile is important: it records a dependency graph that can be reproduced on another development machine, in staging, and in production.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
A failed install is therefore not automatically a reason to delete Gemfile.lock. Removing it discards the known version set and asks Bundler to calculate a new graph, which can introduce unrelated upgrades and additional conflicts. Keep the lockfile under version control unless you have deliberately decided to regenerate and review the complete dependency set.
Start with an evidence-preserving check
Run the commands below from the directory that contains the Rails application’s Gemfile. Save the entire error output before trying fixes. The gem named in the error, the Ruby version, the Bundler version, and any path to mkmf.log usually determine the correct branch of troubleshooting.
#1 Best Overall
ruby -v
which ruby
bundle -v
bundle env
bundle checkruby -vshows the interpreter version Bundler will use.which rubyreveals whether that interpreter comes from Ubuntu, a version manager, or another installation on yourPATH.bundle -videntifies the active Bundler release.bundle envprints the Ruby, Bundler, platform, and project context useful for diagnosis.bundle checkreports whether the gems required by the current definition are already installed.
Also inspect the project’s Gemfile, Gemfile.lock, and .ruby-version without editing them yet. Record whether the lockfile is present, whether the Gemfile has just been changed, and whether the requested Ruby matches the executable reported by ruby -v.
Classify the failure before changing anything
The wording of the error usually points to one of five repair paths. Use this table as a first decision point, then follow the detailed section for that class of failure.
| Visible symptom | First evidence to inspect | Smallest typical repair |
|---|---|---|
Failed to build gem native extension, extconf.rb failed, Could not create Makefile, or a missing header |
The gem name and the mkmf.log path printed by the error |
Install the compiler and only the Ubuntu development package named by the log; retry |
| “Could not find compatible versions” or a long chain of requirements | Every requirement in the dependency chain and the gem you recently changed | Update that gem first, using conservative updating when appropriate |
| Ruby version requirement, Bundler version, or lockfile-version mismatch | ruby -v, which ruby, bundle -v, .ruby-version, Gemfile Ruby declaration, and the lockfile’s Bundler information |
Select the intended Ruby and invoke a compatible Bundler version |
| Certificate, TLS, or rubygems.org connection error | Output from bundle doctor ssl, plus proxy and CA configuration |
Repair the OpenSSL/CA/proxy issue identified by the diagnostic |
| Permission denied, unexpected install location, or missing groups | bundle config list, the effective user, and the configured path/groups |
Correct the path, ownership, deployment mode, or group settings |
Fix native-extension and compiler errors
Read mkmf.log first
Native gems compile C or C++ code while installing. Typical messages are Failed to build gem native extension, extconf.rb failed, and Could not create Makefile. RubyGems identifies the most common cause as a missing compiler toolchain and directs you to the mkmf.log path printed in the failure.
Open the log at the exact path shown by Bundler. Look for the first missing command, header, or library rather than the final cascade of errors. A line such as fatal error: sqlite3.h: No such file or directory is more useful than the final “make failed” message because it identifies the development package that is absent.
Install Ubuntu’s basic toolchain for distribution Ruby
If Ruby came from Ubuntu’s packages, install the standard compiler toolchain and Ruby headers, then retry:
sudo apt-get update
sudo apt-get install build-essential ruby-dev
bundle installbuild-essential supplies the ordinary compiler, linker, and make tools. ruby-dev supplies headers needed to compile extensions against Ubuntu’s packaged Ruby. A Ruby built by a version manager has its own headers, so installing ruby-dev is not automatically the right answer in that case; first confirm which Ruby which ruby selected.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsInstall the development package named by the error
Many extensions also depend on a system library. Install the matching Ubuntu -dev package, not a random collection of development packages. Depending on the gem, the missing item may relate to SQLite, PostgreSQL, libxml2/libxslt, or OpenSSL. The exact package name varies by gem and Ubuntu release, so use the header or library named in mkmf.log and the gem’s installation documentation to select it.
Rank #2
For example, an error naming a database header calls for that database’s development package; it does not indicate a Bundler version problem. After installing the identified package, run the same bundle install again and check whether the error moves to a different, specifically named dependency.
Do not hide a compiler problem with dependency changes
Changing gem versions cannot create a missing compiler or header. Avoid updating Rails or unrelated gems while the log clearly reports a system prerequisite. Keep the lockfile intact, install the prerequisite, and compare the new output with the original failure.
Resolve dependency-version conflicts without rebuilding everything
Read the requirement chain
When Bundler says it could not find compatible versions, the message describes a chain: one gem requires a range of versions of another gem, while your Gemfile or another locked dependency requires a range that does not overlap. Read the chain from the gem you changed through each transitive requirement until you reach the conflicting constraint.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check whether the conflict appeared after adding a gem, changing a version constraint, switching branches, or changing the Ruby platform. The first changed requirement is usually the safest place to begin.
Update only the gem you changed
Use a targeted update rather than a full graph refresh:
bundle update GEMReplace GEM with the dependency you intentionally changed. Bundler will reconsider that gem and the dependencies it must move, while leaving unrelated locked versions alone where possible.
Use conservative updating for indirect dependencies
If the direct gem can move but you want indirect dependencies to remain locked unless movement is required, use:
bundle update GEM --conservativeThis is useful when a small application change should not trigger a broad upgrade of the dependency graph. Review the resulting lockfile diff before committing it.
Loosen constraints deliberately
If the requirement chain proves that no overlap exists, you may need to loosen a Gemfile constraint or choose a compatible release. Do this only after identifying which constraint blocks resolution. A broad change such as removing multiple version limits makes the eventual graph harder to explain and reproduce.
bundle outdated can show stale dependencies, but staleness alone is not a reason to update everything while diagnosing one failure. Separate routine maintenance from the immediate repair, and test each intentional dependency change.
Fix Ruby and Bundler version mismatches
Compare every version declaration
Check all of these values together:
- The interpreter selected by
which rubyand its version fromruby -v. - A Ruby requirement in the Gemfile, if one is declared.
- The version in
.ruby-version, if the project uses that file. - The active Bundler release from
bundle -v. - The Bundler version recorded in the lockfile and the version that created or last updated it.
A shell can appear to have the right Ruby while invoking another executable earlier on PATH. That is why both which ruby and ruby -v matter. A project may also require a Bundler release that is not the one installed globally.
Free tools Windows power users keep installed
One-click scans. No signup required.
Select the project’s Ruby before changing gems
Use the project’s documented Ruby and its version-manager setup, then verify again with ruby -v and which ruby. Rails’ Bundler guidance recommends a dependable Ruby installation such as RVM when switching between Ruby versions; any consistently configured version manager can serve the same purpose.
Once the intended Ruby is active, install or invoke the Bundler version compatible with the project. Do not simultaneously upgrade Ruby, Rails, Bundler, and every gem. Changing several variables removes the evidence needed to identify which requirement was incompatible.
Regenerate only when the project intends to change the lockfile
If the Gemfile and Ruby requirement are unchanged, the normal expectation is installation of the versions already locked. If a deliberate Ruby or dependency upgrade requires a new lockfile, make that a separate change, review the complete diff, and run the application’s test suite rather than treating lockfile regeneration as a generic repair.
Repair SSL, certificate, and rubygems.org failures
Run Bundler’s SSL diagnostic
For errors mentioning certificates, TLS, secure connections, or inability to reach rubygems.org, run:
Recommended Free Tools
bundle doctor sslThis check examines Ruby’s OpenSSL setup, the available CA certificates, and the TLS connection to rubygems.org. Follow the specific problem it reports. Possible causes include an outdated or missing CA bundle, an OpenSSL installation that the active Ruby cannot use, or a corporate proxy that is not configured for the process running Bundler.
Repair the identified trust or proxy problem
Correct the CA, OpenSSL, or proxy configuration named by the diagnostic, then rerun the same command and bundle install. Verify that the Ruby used by the shell is the one whose OpenSSL configuration you repaired; fixing a system Ruby does not necessarily fix a version-manager Ruby.
Do not disable certificate verification as a permanent workaround. It removes the protection that authenticates the gem server and can conceal a configuration problem that will return on another machine or in deployment.
Correct deployment paths, permissions, and groups
Check effective Bundler settings
bundle config listReview the displayed path, deployment mode, excluded groups, build options, and any environment-specific settings. A setting in the local project, the user’s home directory, or an environment variable can change behavior even when the command itself is simply bundle install.
Understand deployment mode
Deployment mode installs gems into vendor/bundle unless another path has been configured. The application user must be able to create and write to that directory. Run Bundler as the intended application user, not as root merely to bypass a permission error; root-owned files commonly cause the next deployment to fail for the normal user.
Understand groups correctly
Group settings can exclude installation of groups such as development or test, but Bundler still resolves the full dependency set when it creates the lockfile. An excluded group therefore does not remove its dependency constraints from resolution. Confirm the effective group configuration with bundle config list and ensure the deployment command matches the environment’s intended groups.
Best Value
Check ownership and the selected path
If the error is “permission denied,” inspect the owner and permissions of the configured installation path and its parent directories. If the path is unexpected, correct the Bundler configuration instead of moving gems manually. A reproducible deployment has the same configured path and user expectations on each host.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Retry with the smallest possible change
After correcting the identified cause, run:
bundle installCompare the output with the saved original error. With an unchanged Gemfile and a present lockfile, Bundler should install the locked gems rather than perform a broad dependency upgrade. If the retry produces a new error, classify that new error independently; do not assume the first diagnosis still applies.
Run bundle check after a successful install. Then start the Rails application or run the project’s normal test command as the same user and Ruby environment used for installation. A successful download does not prove that the application can load every extension or access every runtime service.
Choose between competing repairs
When two fixes seem possible, compare them against the project’s reproducibility requirements:
| Repair question | Prefer the option that… | Reason |
|---|---|---|
| Does it preserve the committed lockfile? | Keeps the lockfile and changes only the necessary prerequisite or targeted dependency | Preserves the known dependency graph |
| Does it change the Ruby runtime? | Uses the Ruby already required by the project, unless a deliberate runtime upgrade is being performed | A runtime change can alter native compilation and dependency resolution |
| Does it add system packages? | Adds only the compiler, Ruby headers, or library development package named by the error | Avoids unrelated system changes |
| Does it alter deployment behavior? | Matches the configured path, user, mode, and groups | Prevents “works locally” installation differences |
| Does it address TLS? | Repairs the CA, OpenSSL, or proxy issue identified by bundle doctor ssl |
Fixes trust validation instead of bypassing it |
Common mistakes that make the failure worse
- Deleting
Gemfile.lockfirst: this replaces a known graph with a newly resolved one and can create unrelated conflicts. - Running as root: it can leave root-owned gems or
vendor/bundlecontent that the application user cannot update. - Installing every conceivable
-devpackage: the missing header inmkmf.logis a better guide than a broad package dump. - Updating all gems during one failure: it changes too many variables to identify the original incompatibility.
- Ignoring
.ruby-version: a shell’s default Ruby may not be the project’s Ruby. - Disabling TLS verification: it hides certificate problems and weakens the connection to the gem server.
- Assuming excluded groups are not resolved: Bundler still considers the full dependency set when writing the lockfile.
A repeatable Ubuntu troubleshooting checklist
- Change into the Rails project directory containing
Gemfile. - Save the complete error, including the gem name and any
mkmf.logpath. - Run
ruby -v,which ruby,bundle -v,bundle env, andbundle check. - Check the Gemfile Ruby requirement,
.ruby-version,Gemfile.lock, and the recent change that preceded the failure. - For native compilation, read
mkmf.log, installbuild-essentialand (for Ubuntu’s packaged Ruby)ruby-dev, then add only the named library development package. - For dependency conflicts, follow the requirement chain and try
bundle update GEM, adding--conservativewhen indirect versions should stay locked. - For Ruby or Bundler mismatches, select the intended Ruby first and use a compatible Bundler version.
- For TLS errors, run
bundle doctor ssland repair the reported CA, OpenSSL, or proxy issue. - For path, permission, or group errors, inspect
bundle config listand run as the intended application user. - Retry
bundle install, runbundle check, and review any lockfile change before committing it.
Keeping future installs reproducible
Commit Gemfile.lock for applications so every environment starts from the same resolved versions. Document the required Ruby and Bundler versions, keep .ruby-version consistent with that documentation, and install system development packages as part of the Ubuntu setup procedure rather than discovering them during deployment.
When changing a dependency, make one focused commit, use a targeted update, and review the lockfile diff. When changing the Ruby runtime or Bundler, treat that as a separate migration with its own test run. These habits preserve the evidence that makes the next bundle install failure diagnosable.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
