Failed to build gem native extension Ruby / Rails Origin: Application & API OSI layer 7 · Application Last updated 5 Nov 2026

Ruby: ERROR: Failed to build gem native extension. current directory: /gems/pg-1.5.4/ext/pg — An error occurred while installing pg

A gem with C code couldn't compile, usually because a system library or header is missing.

Exact message you may see ERROR: Failed to build gem native extension.An error occurred while installing pg (1.5.4), and Bundler cannot continueGem::Ext::BuildError: ERROR: Failed to build gem native extension.mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.hfatal error: libpq-fe.h: No such file or directory
Explore the map of this error Full error map →
Seen on: Ruby Linux

Meaning

Read mkmf.log/the lines before the error: missing libpq-dev (pg), libmysqlclient-dev (mysql2), libxml2/libxslt (nokogiri source build), libsqlite3-dev, build-essential/Xcode CLT, ruby-dev headers. Install the dev package and re-run bundle install.

Common causes

  • Missing dev headers (libpq-dev, libmysqlclient-dev, ruby-dev)
  • No compiler/build tools
  • Apple Silicon/Homebrew library paths
  • Wrong Ruby version for the gem
  • Outdated gem version incompatible with new Ruby

⚡ Quick fix

  1. Debian: sudo apt install build-essential ruby-dev libpq-dev (as needed)
  2. macOS: xcode-select --install; brew install libpq and bundle config build.pg --with-pg-config=$(brew --prefix libpq)/bin/pg_config
  3. Upgrade the gem

Detailed fix by platform

Linux

  1. less $(gem env gemdir)/extensions/*/*/pg-*/mkmf.log

How to diagnose

  1. Gem — Which?
  2. Header — Missing lib?
  3. Tools — Compiler installed?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Application & API. Errors that are often confused with or caused by this one (click to open):

ArgumentError: missing keyword / unknown keyword — Ruby: ArgumentError: missing keyword: :name / unknown keyword: :nmae (Ruby / Rails)ArgumentError: missin…ArgumentError: wrong number of arguments (given 1, expected 2) — Ruby: ArgumentError: wrong number of arguments (given 1, expected 2..3) (Ruby / Rails)ArgumentError: wrong …Bundler could not find compatible versions for gem — Bundler: Bundler could not find compatible versions for gem "activesupport": In Gemfile: rails (= 7.1.0) depends on activesupport (= 7.1.0) (Ruby / Rails)Bundler could not fin…Bundler: Could not find gem in locally installed gems — Bundler: Could not find gem 'rails (~> 7.1)' in locally installed gems / Could not find rails-7.1.0 in any of the gem sources listed in your Gemfile (Ruby / Rails)Bundler: Could not fi…ld: library not found for -lssl — macOS: ld: library 'ssl' not found / ld: library not found for -lssl (clang: error: linker command failed) (macOS)ld: library not found…LoadError: cannot load such file — Ruby: LoadError: cannot load such file -- nokogiri (or: cannot load such file -- bundler/setup) (Ruby / Rails)LoadError: cannot loa…Nokogiri: could not find a platform gem / libxml2 build error — Bundler: Your bundle only supports platforms ["x86_64-linux"] but your local platform is arm64-darwin / Could not find gem 'nokogiri (1.16.0-arm64-darwin)' (Ruby / Rails)Nokogiri: could not f…Failed to…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.