はじめに

Rails API プロジェクトの初期構築時、bundle install でエラーが発生しました。この記事ではその原因と対処法を、実行コマンドとあわせてまとめています。同じようなエラーで悩んでいる方の参考になれば嬉しいです。

エラー内容（再現ログ）

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

In Gemfile:
  pg

Could not find rails-7.1.5.1, pg-1.5.9, nokogiri-1.18.8, and others in locally installed gems.

開発環境

OS：Ubuntu 22.04（WSL2でも可）
Ruby：3.2.2
Rails：7.1.5.1（--api モード）
PostgreSQL：利用予定
Bundler：2.4.x

解決手順と実行コマンド

1. 必要なライブラリのインストール

Rails の一部 gem（特に pg や nokogiri）は、ビルドに C/C++ ライブラリが必要です。

# PostgreSQL 関連（pg 用）
sudo apt update
sudo apt install libpq-dev

# Nokogiri 関連
sudo apt install build-essential libxml2-dev libxslt-dev zlib1g-dev liblzma-dev

2. Nokogiri のビルドエラー対策

bundle config build.nokogiri --use-system-libraries
bundle install

もしくは以下のように個別インストール：

gem install nokogiri --platform=ruby -- --use-system-libraries

3. Gemfile.lock のリセット（依存関係の不整合回避）

rm Gemfile.lock
bundle install

4. Ruby / Bundler バージョンの確認・更新

ruby -v
bundle -v
gem install bundler

Rails 7.1.x 系は Ruby 3.2 以降で安定して動作します。

結果と学び

手順をすべて実行した後、bundle install が正常に完了し、Rails API プロジェクトを起動できるようになりました。ネイティブ拡張を含む gem は環境に依存するため、事前の準備と理解が重要だと実感しました。

さいごに

初期構築時のエラーは誰もがつまずきがちですが、原因調査や対処ログを記録しておくと、今後の学習に大いに役立ちます。今後もこうした初歩的な内容を積極的に記事にしていきたいです。