Most Rails bundle install failures on Ubuntu become straightforward once you identify which layer failed: the compiler and headers for a native extension, Bundler’s dependency solver, the Ruby or Bundler runtime, TLS certificates, or the install path and groups. Start by preserving the complete error and checking the exact Ruby and Bundler in use. Then make the smallest change that addresses that evidence.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What bundle install is supposed to do
Run Bundler from the directory that contains the Rails application’s Gemfile. Bundler reads the dependency declarations there and installs the resulting set of gems. If Gemfile.lock is present and the Gemfile has not changed, the normal operation is to install the versions recorded in that lockfile rather than resolve an entirely new set.
As an Amazon Associate I earn from qualifying purchases.
The lockfile is therefore part of the application’s build input, not disposable cache data. Keep it under version control so development, CI, staging and production can reproduce the same dependency graph. Deleting it as a first response can replace a known graph with a different one and introduce failures unrelated to the original error.
Bundler can still change what gets installed without changing the resolved graph. Deployment mode normally installs into vendor/bundle (unless another path is configured), and group settings can exclude installation of groups such as development or test. Those settings affect the installed files, while Bundler still resolves the complete dependency set when it creates or updates the lockfile.
#1 Best Overall
1. Preserve the evidence and establish a baseline
Before installing packages or editing dependency constraints, capture the whole terminal error. Include the gem named in the failure, the Ruby version, the Bundler version and any path printed for mkmf.log. Run these checks in the application directory:
ruby -v— records the interpreter version actually being executed.which ruby— shows which executable is first on yourPATH; this catches a shell using system Ruby when the project expects a version-manager Ruby, or the reverse.bundle -v— records the Bundler release running the command.bundle env— prints the Ruby, Bundler, platform and project context useful for comparing a failing machine with a working one.bundle check— reports whether the gems required by the current definition are already installed.
Do not run the command from a parent directory or another project. A different Gemfile or a different local Bundler configuration can make a valid environment appear broken.
Free tools Windows power users keep installed
One-click scans. No signup required.
2. Classify the failure before changing anything
| What the output says | What it usually indicates | First evidence to inspect |
|---|---|---|
Failed to build gem native extension, extconf.rb failed, or Could not create Makefile |
A compiler, Ruby header, system library, or development header is missing | The gem’s mkmf.log path and the first missing command or header named there |
| Could not find compatible versions; a chain of conflicting requirements | Two or more Gemfile or gemspec constraints cannot be satisfied together | Every requirement in the chain, including the gem you changed most recently |
| The project requires another Ruby, or the lockfile was made with another Bundler | The executable, project Ruby declaration, .ruby-version, or Bundler release does not match |
ruby -v, which ruby, the ruby line in the Gemfile, .ruby-version, and bundle -v |
| Certificate, TLS, or connection errors while contacting rubygems.org | OpenSSL, CA certificates, system time, or a proxy is misconfigured | The output of bundle doctor ssl |
| Permission denied, unexpected install location, or missing groups | Deployment mode, Bundler settings, path ownership, or excluded groups differ | bundle config list, the target directory and the user running Bundler |
3. Repair native-extension and compiler failures
Native gems compile C or C++ code during installation. RubyGems’ troubleshooting guide states that “The most common cause is a missing compiler toolchain.” The same guide directs you to the mkmf.log path printed by the failure; that file normally contains the compiler command, the header or library test that failed and the operating-system error.
Install Ubuntu’s basic build tools for distribution Ruby
For Ruby supplied by Ubuntu’s packages, install the compiler toolchain and Ruby development headers, then retry:
sudo apt-get update
sudo apt-get install build-essential ruby-dev
bundle installbuild-essential supplies the standard 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 generally carries its own headers; installing ruby-dev does not repair a mismatch between two different Ruby installations. Confirm which interpreter which ruby reported before choosing packages.
Rank #2
Install only the development library named by the log
If mkmf.log names a missing header or library, install the corresponding Ubuntu development package rather than adding a random collection of packages. Common examples are development packages for SQLite, PostgreSQL, libxml2/libxslt or libssl, but the exact package name depends on the gem and your Ubuntu release. Use the header name and the gem’s installation documentation to select it. After installing that one prerequisite, rerun bundle install and inspect whether the same test still fails.
Recommended Free Tools
Read the failure in the right order
- Open the exact
mkmf.logpath printed by Bundler; do not rely only on the final one-line summary. - Find the first failed test for a compiler executable, Ruby header, system header or library.
- Install or repair that prerequisite for the Ruby executable reported by
which ruby. - Retry with the same Gemfile and lockfile so the result tests one change.
If the log changes to a different missing header, treat that as the next concrete prerequisite. If it reports a compiler error in the gem’s source rather than a missing file, check that the gem version supports your Ruby and platform before changing unrelated dependencies.
4. Resolve incompatible gem requirements without discarding the lockfile
A version-solver error is a requirement chain, not a command to upgrade everything. Read from the root requirement in your Gemfile through each dependent gem until the incompatible bounds are visible. The chain often identifies the gem you edited, a plugin that limits its upper version, or a Rails component that has not yet added support for the Ruby version in use.
Update the gem you changed first
When you intentionally changed one dependency, ask Bundler to reconsider that dependency rather than the entire graph:
bundle update GEMReplace GEM with the actual gem name. If indirect dependencies should remain at their locked versions whenever possible, use conservative updating:
bundle update GEM --conservativeThis keeps the update focused and makes the resulting lockfile diff reviewable. Read the changed entries before committing them.
Inspect stale dependencies before loosening constraints
bundle outdated lists dependencies with newer releases. Use it to see whether the conflict is caused by an old direct dependency, but do not treat every available upgrade as required. A deliberate constraint change is appropriate only when the requirement chain proves that the current bounds cannot be satisfied. Widen the specific constraint, update the dependent gem that imposes it, or choose a compatible release; record why the change is needed.
Do not use lockfile deletion as a solver strategy
Removing Gemfile.lock allows Bundler to choose a new graph for every dependency at once. That can hide the original conflict while introducing different Rails, adapter or platform incompatibilities. Preserve a copy if an emergency experiment is unavoidable, and restore the committed lockfile before testing the targeted fix.
5. Align Ruby, the project declaration and Bundler
There are several independent version authorities. The Gemfile may contain a Ruby requirement; .ruby-version may select the interpreter for the directory; the shell chooses an executable through PATH; and Gemfile.lock records the Bundler version that last generated it. A mismatch in any of these can stop installation before dependency resolution is meaningful.
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 errorsCheck the project before changing dependencies
- Read the Gemfile’s
rubydeclaration, if present. - Read
.ruby-version, including whether it specifies a patch-level release or an environment-manager alias. - Compare both with
ruby -vandwhich ruby. - Run
bundle -vand compare that release with the Bundler information recorded in the lockfile.
Select the project’s intended Ruby first. If the project switches between Rubies, use a dependable version manager; the Rails Bundler guidance gives RVM as an example. Once the correct interpreter is active, install or invoke the Bundler release compatible with the project and its lockfile. Avoid upgrading Rails, Ruby and every gem in the same attempt: changing several variables removes the evidence needed to identify the incompatible requirement.
Recognize a system-Ruby mix-up
A common symptom is that Ruby appears to be installed, yet a native extension cannot find headers or a gem requires a different Ruby. This often means the shell is invoking a different Ruby from the one for which packages were installed. Re-check which ruby in the same terminal session that runs Bundler, activate the project’s selected Ruby, and then repeat bundle env so the complete context is visible.
6. Fix SSL and certificate errors safely
For failures connecting to rubygems.org, run:
bundle doctor sslBundler’s SSL diagnostic checks Ruby’s OpenSSL setup, the CA certificate store and the TLS connection to rubygems.org. Follow the specific repair it reports: that may mean correcting the CA bundle, repairing the OpenSSL installation, fixing a proxy setting or correcting the machine’s trust configuration. Retry only after the diagnostic no longer identifies the same problem.
Do not turn off certificate verification as a permanent workaround. It converts a detectable trust failure into an opportunity for a man-in-the-middle attack and can leave future gem downloads unverified.
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 →7. Correct deployment paths, permissions and groups
Deployment mode normally installs gems under vendor/bundle, unless a different path is configured. A permission error in that directory is an ownership or execution-user problem, not a dependency conflict. Check the effective settings with:
bundle config listConfirm that the path exists, that the application user can create and modify files there, and that you are running Bundler as the user intended for the deployment. Avoid solving a permissions problem by running the whole application install as an unrelated administrator; that can leave root-owned files that later prevent the service account from updating gems.
Best Value
Group settings can omit installation of selected groups, but they do not remove those gems from dependency resolution when Bundler creates the lockfile. If a test or development gem appears absent, inspect the configured excluded groups before editing the Gemfile.
8. Retry with the smallest change
After correcting the identified cause, rerun bundle install with the same project files. If the Gemfile and lockfile are unchanged, the expected result is installation of the locked versions, not a broad upgrade. Compare the new output with the saved error:
- A native-extension failure should move past the missing compiler, header or library named in
mkmf.log. - A solver failure should show a narrower lockfile change tied to the gem or constraint you deliberately updated.
- A runtime mismatch should disappear once the selected Ruby and Bundler match the project.
- An SSL failure should disappear only after
bundle doctor sslstops reporting the underlying trust or TLS defect. - A path failure should show Bundler writing to the configured directory as the intended user.
If the same error returns unchanged, restore the previous state and inspect the original evidence again instead of layering another unrelated change on top.
Choosing between possible repairs
When several fixes appear plausible, compare them against the same five questions: does the change preserve the committed lockfile, does it alter the Ruby runtime, does it add only headers named by the error, does it affect deployment paths or permissions, and does it address the exact TLS or proxy diagnostic?
| Repair | Lockfile impact | Ruby runtime impact | Typical scope |
|---|---|---|---|
Install build-essential, ruby-dev, or the specific -dev package named by mkmf.log |
Preserves it | None | Native compilation prerequisite |
bundle update GEM --conservative |
Changes only the targeted dependency and required edges | None | Focused solver repair |
| Switch to the Ruby specified by the project | Usually preserves it, provided the Ruby supports the locked gems | Changes the interpreter | Runtime or native-ABI mismatch |
Repair CA, OpenSSL or proxy configuration identified by bundle doctor ssl |
Preserves it | None unless Ruby itself is rebuilt | Trust and transport failure |
| Correct Bundler path, group or ownership settings | Preserves it | None | Deployment and permissions |
Failure patterns that make diagnosis harder
- Deleting the lockfile immediately: removes the known dependency graph and makes the next error harder to relate to the first one.
- Installing every development package you can find: obscures which header was missing and increases the maintenance surface; use
mkmf.logto choose the matching package. - Running Bundler under a different user: creates ownership problems in
vendor/bundleor the configured path. - Updating Rails, Ruby and all gems together: changes too many variables to identify the incompatible requirement.
- Ignoring
.ruby-versionorwhich ruby: leaves Bundler attached to an interpreter other than the one you intended. - Disabling TLS verification: hides a certificate problem while weakening the security of every gem download.
A compact recovery checklist
- Run from the directory containing the Rails Gemfile.
- Save the complete error and the
mkmf.logpath, if present. - Run
ruby -v,which ruby,bundle -v,bundle envandbundle check. - Classify the message as native build, dependency resolution, Ruby/Bundler mismatch, SSL, or path/groups.
- Apply only the corresponding fix: compiler and headers, a focused gem update, the intended runtime, the SSL repair, or the configuration/ownership correction.
- Keep
Gemfile.lockunder version control and review any deliberate change to it. - Retry
bundle installand compare the output with the original evidence.
The Bottom Line
On Ubuntu, reliable Bundler repairs come from matching the evidence to one layer at a time: read mkmf.log for native builds, follow the requirement chain for conflicts, align Ruby and Bundler before changing gems, use bundle doctor ssl for TLS, and verify deployment settings and ownership. Preserve the lockfile throughout so the fix remains reproducible.
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.
