Rails 7で 'local' is a reserved environment name エラーが発生した場合の原因と解決策

概要

Railsのバージョンを5系から7系に段階的にアップデートした際、Rails 7系でサーバーが起動しなくなるエラーに遭遇しました。

エラー内容は 'local' is a reserved environment name (ArgumentError) というもので、原因と解決策について調査した内容を共有します。

現象

Rails 7.2.2.1 にアップデート後、サーバーを起動しようとしたところ以下のエラーが発生しました。

/usr/local/lib/ruby/gems/3.3.0/gems/activesupport-7.2.2.1/lib/active_support/environment_inquirer.rb:16:in `initialize': 'local' is a reserved environment name (ArgumentError)       
raise(ArgumentError, "'local' is a reserved environment name") if env == "local"             
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

‍

このエラーにより、サーバーの起動ができなくなりました。

原因

対象のRailsプロジェクトでは、以下のように3つの環境を用意して運用していました。

• local（ローカル開発用）
• development（開発環境）
• production（本番環境）

しかし、Rails 7.1以降、Active Supportの environment_inquirer.rb にて、localという環境名は予約された名前とみなされるようになり、使用すると ArgumentError が発生するように変更されました。

背景

• 該当PR では、local を環境名として使用できないようにする修正が入っており、テストケース名も "prevent local from being used as an actual environment name" となっています。
• この変更により、Rails.env = 'local' のようなケースはエラーとなる仕様です。
• 通常の rails new で作成されるアプリでは、デフォルトで development, production, test の3つの環境のみが用意されており、local を独自に追加する事例は少ないため、インターネット上にも同様の事例があまり見当たらないと考えられます。

また、EnvironmentInquirer という内部クラスがRails公式APIドキュメントには掲載されておらず、挙動に気づきにくい点も影響しています。

• Rails API公式サイト

解決策

local という名称が使えないため、代替となる環境名（例：development_local）を使用することで問題を回避しました。

修正した内容の例

• 条件分岐の見直し：

# 変更前
if Rails.env.local?
# 変更後
if Rails.env.development_local?

• 環境設定ファイルのリネーム：

config/environments/local.rb → config/environments/development_local.rb

• database.yml, storage.yml などの設定名：‍


# 変更前
local:  
...
# 変更後
development_local:  
...

• fixtures ディレクトリ内のフォルダ名（意外と見落としやすい）：

db/fixtures/local/xxx.rb → db/fixtures/development_local/xxx.rb

• マスターキーのファイル名：

config/master-local.key → config/master-development_local.key

まとめ

Rails 7.1以降では、local という環境名が予約されており使用できなくなっています。

ローカル開発環境として local を使っていた場合は、名称を development_local などに変更することで、エラーを解消することができます。

‍

‍