DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
Skip to content
VGSources
Blog

Fixing Bundle Install Errors for Rails on Ubuntu

A practical, evidence-first guide to Rails bundle install failures on Ubuntu, covering native extensions, dependency conflicts, Ruby and Bundler versions, SSL diagnostics, deployment paths and permissions.
Length10 min Posted Quest giverVGSources Team
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Start by preserving the complete error, then identify which layer failed: a native extension, dependency resolution, Ruby or Bundler version selection, TLS, or the install path. Run the checks from the Rails application directory, keep Gemfile.lock intact, and make the smallest change that addresses the evidence. Most native-extension failures on Ubuntu are fixed by installing the compiler toolchain and the development headers named in mkmf.log; version and dependency failures require a deliberate change to the runtime or dependency constraints instead.

What bundle install actually does

Bundler reads the Rails application’s Gemfile, resolves the declared gems and their dependencies, and installs the resulting set. If Gemfile.lock is present and the Gemfile has not changed in a way that requires re-resolution, Bundler uses the versions recorded in that lockfile rather than selecting an entirely new set. That distinction matters: a failed install is usually an environment or prerequisite problem, not a reason to erase the lockfile.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The lockfile is the project’s reproducibility record. It lets development, CI, staging and production use the same resolved versions. Deleting it can make the immediate command appear to progress while replacing a known dependency graph with a newly resolved graph and unrelated incompatibilities.

File or command What it tells you Why it matters during a failure
Gemfile Direct dependency declarations and version constraints A changed constraint can trigger a new resolution
Gemfile.lock The resolved versions and dependency graph Preserves the known-good set across machines; keep it under version control
bundle check Whether the requirements are installed Separates a missing installation from a resolution problem
bundle env Bundler, Ruby and project context Provides the runtime details needed to reproduce the failure
bundle config list Effective Bundler settings Reveals custom paths, deployment mode and excluded groups

Preserve evidence before changing anything

Run the command from the directory containing the Rails app’s Gemfile. Save the entire terminal output, not just the final line. The gem name, Ruby version, Bundler version, compiler message and any printed path to mkmf.log determine the correct repair.

#1 Best Overall
Sale
Gaoye Blue Light Blocking Glasses
  • BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
  • EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
  • COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
  • LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
  • WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
  1. Record the runtime. Run ruby -v and which ruby. The first command reports the version; the second shows which executable is actually being used.
  2. Record Bundler and its context. Run bundle -v and bundle env. This catches a shell that is using a different Ruby or Bundler than the one expected by the project.
  3. Check the current installation state. Run bundle check. Its result indicates whether required gems are already installed, but it does not replace diagnosis of a compiler or TLS error.
  4. Inspect project constraints. Read the Ruby requirement in the Gemfile, check .ruby-version if present, and note the Bundler version recorded in the lockfile. Compare all of them with the commands above.
  5. Keep the lockfile. Do not remove Gemfile.lock as a first response. Make a backup or commit unrelated edits before experimenting so that the original dependency state remains recoverable.

These checks also prevent a common misdiagnosis: running bundle install with a system Ruby when the project was created with a version-manager Ruby, or running it from a parent directory that contains a different Gemfile.

Fix native-extension and compiler failures

Messages such as Failed to build gem native extension, extconf.rb failed, Could not create Makefile, or a missing header usually mean that a gem must compile C or C++ code and the operating system lacks a required tool. RubyGems’ troubleshooting guidance says, “The most common cause is a missing compiler toolchain.”

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Read mkmf.log first

The failed build prints the path to mkmf.log. Open that file and look for the first missing command, header, library or configuration test. The final Bundler error is often only a summary; mkmf.log identifies the actual prerequisite. For example, an error naming a SQLite, PostgreSQL, libxml2, libxslt or OpenSSL header points to that library’s Ubuntu development package, not to an arbitrary collection of packages.

Install Ubuntu’s basic build prerequisites

For Ubuntu’s packaged Ruby, install the compiler toolchain and Ruby headers, then retry:

sudo apt-get update
sudo apt-get install build-essential ruby-dev
bundle install

build-essential supplies the standard compiler and build utilities. ruby-dev supplies headers needed when the Ruby interpreter came from Ubuntu’s distribution packages. If Ruby was compiled or installed by a version manager, that Ruby may already include its own headers; installing ruby-dev is not a substitute for selecting the correct version-manager environment.

Install only the library named by the log

If the log reports a missing system header or library, install the matching Ubuntu -dev package for that dependency and the Ubuntu release in use. Typical families include development packages for SQLite, PostgreSQL, libxml2/libxslt and libssl, but the exact package name depends on the gem and release. Confirm the name from the log and the gem’s installation documentation instead of adding unrelated packages.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Windex Gaming Cleaning Wipes, Pre-Moistened Wipes to Instantly Clean all Gaming Gear and Electronics, Resealable Packaging for a Freshness Lock, 25 count (Pack of 1)
  • WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
  • AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
  • PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
  • ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
  • COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
Symptom in the build output Likely next check Repair approach
Could not create Makefile or compiler not found Whether build-essential is installed Install the toolchain, then rerun the same command
Ruby header such as ruby.h is missing How Ruby was installed Install ruby-dev for distribution Ruby, or select/install headers for the version-manager Ruby
Database or XML header is missing The exact header named in mkmf.log Install the corresponding Ubuntu library development package
OpenSSL header or library cannot be found OpenSSL development files and the selected Ruby’s build configuration Install the required development package or rebuild/select Ruby with a usable OpenSSL

After installing a prerequisite, rerun bundle install without changing gem versions. If the failure moves to a different missing header, repeat the same evidence-based process. If the log instead shows an incompatible compiler flag or Ruby API, stop adding packages and investigate the gem version against the selected Ruby.

Resolve “could not find compatible versions” errors

A dependency-resolution failure is a requirements chain, not a single bad gem. Read the error from the top-level gem through each constraint until you find the incompatible pair. One gem may require an older dependency while another requires a newer release, or the project may constrain a gem more tightly than its current Ruby supports.

Update the gem you intentionally changed

If you edited one dependency, update only that gem first:

bundle update GEM

Replace GEM with the gem whose constraint or version you changed. This keeps unrelated locked versions in place and makes the resulting lockfile diff understandable.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use conservative updating for indirect dependencies

When the direct gem must move but its indirect dependencies should remain locked where possible, use:

bundle update GEM --conservative

Conservative updating limits collateral upgrades. It is useful when a security or feature change targets one gem but the application has not been tested against a wholesale dependency refresh.

Rank #3
Sale
LISEN Cell Phone Stand Phone Holder for Desk, Office Decor Gadgets for Men
  • Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
  • Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
  • Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
  • ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
  • Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)

Change constraints deliberately

Loosen a version constraint only when the requirement chain demonstrates that the current constraint prevents a compatible set. Record why the constraint changed and review the resulting lockfile diff. Do not respond to one conflict by upgrading Rails, Ruby and every gem at once; changing several variables removes the evidence needed to identify the incompatible requirement.

Run bundle outdated when you need to see stale dependencies, but treat its output as an inventory, not an instruction to upgrade everything. A package can be outdated and still be the correct locked version for the application’s Ruby and Rails release.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Correct Ruby and Bundler version mismatches

Before altering dependencies, verify that the project is running the Ruby it expects. Compare the Ruby requirement in the Gemfile and .ruby-version with ruby -v and which ruby. A shell can silently select a system executable even when another Ruby is installed.

Select the intended Ruby first

Use the project’s established Ruby version manager or installation method to select the version named by the project. Rails’ Bundler guidance recommends a dependable Ruby installation method when switching between Ruby versions. After selecting Ruby, open a new shell if the manager requires it, then rerun ruby -v and which ruby to confirm the change.

Match Bundler to the project

Compare bundle -v with the Bundler version recorded in Gemfile.lock and any project setup documentation. Install or invoke the compatible Bundler version only after the intended Ruby is active. A Bundler mismatch can alter lockfile handling or reject dependencies even when the gem declarations themselves are valid.

Do not “fix” a runtime mismatch by deleting the lockfile. First make the executable and Bundler match the project, then run bundle install against the existing lockfile. If the project genuinely needs a Ruby upgrade, treat that as a planned compatibility change: update the Ruby requirement, test the application, and review dependency changes separately.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
Ledagic IC+RGBW USB Powered Led Light Bar with App & Remote Control, 2 Pack
  • Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
  • Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
  • 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
  • Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
  • USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC

Repair SSL, certificate and rubygems.org connection errors

When the output mentions certificates, TLS, or an inability to connect to rubygems.org, run Bundler’s diagnostic:

bundle doctor ssl

This check examines Ruby’s OpenSSL setup, trusted CA certificates and the TLS connection to rubygems.org. Follow the specific issue it reports: repair the CA bundle, OpenSSL installation, Ruby build or proxy configuration named by the diagnostic, then retry the original install.

Corporate proxies can replace certificates or require explicit proxy settings. Verify the proxy’s CA certificate is trusted by the Ruby process, not merely by a browser. A successful browser connection does not prove that the Ruby executable selected by which ruby has the same trust store.

Do not disable certificate verification as a permanent workaround. It removes the protection that TLS is supposed to provide and can conceal a damaged or intercepted connection. If the diagnostic cannot identify the cause, preserve its output along with bundle env and investigate the OpenSSL and CA paths used by the active Ruby.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Handle deployment mode, groups, paths and permissions

Some failures occur after dependency resolution because Bundler is installing to a path the current user cannot write, or because deployment settings differ from development settings. Check the effective configuration:

bundle config list

Deployment path

In deployment mode, Bundler installs into vendor/bundle unless another path is configured. Confirm that the application user owns the path and that the filesystem has space. Run the command as the intended application user rather than alternating between an unprivileged account and sudo; mixed ownership commonly creates a directory that later commands cannot update.

Best Value
Sale
HUANUO FlowLift™ Dual Monitor Stand, Fully Adjustable Gaming Monitor Desk Mount for 13–32″ Computer Screens, Full Motion VESA 75x75/100x100 with C-Clamp & Grommet Base, Each Arm Holds 4.4 to 19.8 lbs
  • Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
  • Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
  • Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
  • Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
  • Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.

Groups and the without setting

Bundler can exclude installation groups, such as development or test, through its group settings. Excluding a group changes what is installed locally, but Bundler still resolves the full dependency set when creating the lockfile. Therefore, an excluded gem can still participate in a resolution conflict even though it will not be installed on that host.

Inspect the configured groups and path rather than assuming the command-line environment is clean. Remove an obsolete setting only when you know why it was added, then retry with the project’s intended deployment configuration.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Retry with the smallest possible change

Once the evidence identifies the cause, correct only that cause and rerun the same install:

  1. For a compiler failure, install the missing toolchain or exact development package named by mkmf.log.
  2. For a version mismatch, select the project’s Ruby and compatible Bundler before touching the Gemfile.
  3. For a dependency conflict, update the gem that changed, using --conservative when indirect versions should remain locked.
  4. For TLS, repair the CA, OpenSSL or proxy problem identified by bundle doctor ssl.
  5. For deployment failures, correct the configured path, group selection or ownership and run as the intended user.

Run bundle install again and compare its output with the original. With an unchanged Gemfile and a valid lockfile, the expected operation is installation of the locked gems, not a broad dependency upgrade. Finish by running bundle check; in a Rails project, follow the application’s normal test or boot command to verify that the repaired environment works beyond installation.

Choose between competing repairs

When more than one fix appears possible, prefer the option that changes the least while preserving reproducibility.

Repair option Preserves the committed lockfile? Changes Ruby runtime? Typical risk Use it when
Install the missing compiler or named -dev package Yes No Low; adds an operating-system prerequisite mkmf.log names a missing tool, header or library
Select the project’s existing Ruby and Bundler Yes Uses the intended runtime Low if the versions are documented ruby -v, .ruby-version or lockfile metadata disagree
bundle update GEM --conservative No; changes a focused portion Usually no Moderate; the selected gem and allowed dependents move A deliberate Gemfile change created a requirement conflict
Loosen a Gemfile constraint No; requires a new resolution Usually no Moderate to high; a wider version range may alter behavior The requirement chain proves the current constraint is too narrow
Delete Gemfile.lock No Not necessarily High; every dependency may be re-resolved Only as a planned, reviewed regeneration—not as first-line troubleshooting
Disable TLS verification Yes No Unacceptable security exposure Do not use as a permanent repair

Quick symptom-to-action checklist

  • “Failed to build gem native extension”: open the printed mkmf.log path; install build-essential and, for Ubuntu’s packaged Ruby, ruby-dev; then install only the additional library development package the log names.
  • “Could not find compatible versions”: trace the requirement chain; update the gem you changed; use --conservative for a focused update; keep the lockfile.
  • Ruby syntax or required-version error: compare the Gemfile requirement and .ruby-version with ruby -v and which ruby; select the intended Ruby before changing gems.
  • Bundler version complaint: compare bundle -v with the lockfile’s Bundler metadata and invoke a compatible version.
  • Certificate or TLS failure: run bundle doctor ssl; repair the CA, OpenSSL or proxy issue it identifies; do not bypass verification.
  • Permission or missing-path failure in deployment: inspect bundle config list, check vendor/bundle or the configured path, and run as the application user.
  • Unclear state: save the original output, run bundle env and bundle check, and avoid deleting Gemfile.lock until the cause is understood.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More quests from Patch Notes

  1. How to Set Up a RedM (RDR2) Server in 2026: License Key, txAdmin and server.cfg, Step by StepBlog11min
  2. Best RedM (RDR2) Server Hosting in 2026: Comparing Four Hosts on Slots, Memory and PriceBlog10min
  3. How to Host a Mindustry Server in 2026: server-release.jar, Port 6567 and the Commands That MatterBlog7min
Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.