Wanna see something cool? Check out Angular Spotify 🎧

An error occurred while installing pg (1.5.6), and Bundler cannot continue (when running rails new)

I am installing rails to demonstrate how a traditional server-side rendered web application works on my Mac M2, Sonoma 14.5.

I have followed the instructions from here

Install Ruby

git clone https://github.com/excid3/asdf.git ~/.asdf
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.zshrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.zshrc
echo 'legacy_version_file = yes' >> ~/.asdfrc
exec $SHELL

asdf plugin add ruby
asdf install ruby 3.3.3
asdf global ruby 3.3.3

Confirm that the default Ruby version matches the installed version:

which ruby
#=> /Users/username/.asdf/shims/ruby
ruby -v
#=> 3.3.3

Installing Rails

To install Rails, run the following command:

gem install rails -v 7.1.3.4
rails -v
# Rails 7.1.3.4

Create a new Rails app

To create a new Rails app, use the following command:

rails new music-rails --database=postgresql

Here, I encountered the following error as mentioned on the blog title:

Fetching gem metadata from https://rubygems.org/.........
Installing pg 1.5.6 with native extensions
+ Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    current directory: /Users/trung.vo/.asdf/installs/ruby/3.3.3/lib/ruby/gems/3.3.0/gems/pg-1.5.6/ext
/Users/trung.vo/.asdf/installs/ruby/3.3.3/bin/ruby extconf.rb
Calling libpq with GVL unlocked
checking for pg_config... no
checking for libpq per pkg-config... no
Using libpq from 
checking for libpq-fe.h... no
Can't find the 'libpq-fe.h header
*****************************************************************************

+ Unable to find PostgreSQL client library.

Please install libpq or postgresql client package like so:
  brew install libpq

or try again with:
  gem install pg -- --with-pg-config=/path/to/pg_config

or set library paths manually with:
  gem install pg -- --with-pg-include=/path/to/libpq-fe.h/ --with-pg-lib=/path/to/libpq.so/

*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

*** removed for brevity ***

+ An error occurred while installing pg (1.5.6), and Bundler cannot continue.

In Gemfile:
  pg
     run  bundle lock --add-platform=x86_64-linux
Writing lockfile to /Users/trung.vo/Source/view-transitions-demo/music-rails/Gemfile.lock
     run  bundle lock --add-platform=aarch64-linux
Writing lockfile to /Users/trung.vo/Source/view-transitions-demo/music-rails/Gemfile.lock
     run  bundle binstubs bundler
Could not find pg-1.5.6 in locally installed gems
     rails  importmap:install
Could not find pg-1.5.6 in locally installed gems
Run `bundle install` to install missing gems.
     rails  turbo:install stimulus:install
Could not find pg-1.5.6 in locally installed gems
Run `bundle install` to install missing gems.

Solution

Step 1. Install `libpq`

To resolve the issue, follow these steps:

Install libpq by running the following command:

brew install libpq

After successful installation, you will see the following message:

libpq is keg-only, which means it was not symlinked into /opt/homebrew,
because conflicts with postgres formula.

If you need to have libpq first in your PATH, run:
  echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc

For compilers to find libpq you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/libpq/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/libpq/include"

Step 2. Add `libpq` to the PATH

To add libpq to the PATH, you have two options:

Run the following command as suggested above:

echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc

Alternatively, you can run the link command:

brew link --force libpq

The link command ensures that the library is correctly linked to the path. Without running the link command, the same error will occur.

The link command symlinks the installed package (located in /usr/local/Cellar) to /usr/local. So when you type, for example: $ <name-of-binary> in your terminal (e.g., $ rvm), the package installed via brew is executed.