Fix NoMethodError when environment is missing from shakapacker.yml (#669)

Why
Deploying to staging/custom environments crashed with nil error.

Summary
Added configuration fallback (production) and fixed NODE_ENV
assignment for custom environments like staging.

Key improvements
- Configuration falls back to production for undefined environments
- NODE_ENV auto-set to production for staging and custom environments
- Added logging when fallback occurs for easier debugging

Impact
Existing: No change for standard dev/test/production setups
New: Staging and custom environments work without explicit config

Risks
None. Graceful fallback maintains backward compatibility.

Author: justin808

CHANGELOG.md

@@ -11,7 +11,17 @@
 
 Changes since the last non-beta release.
 
-_No unreleased changes._
+### Fixed
+
+- Fixed NoMethodError when custom environment (e.g., staging) is not defined in shakapacker.yml. [PR #669](https://github.com/shakacode/shakapacker/pull/669) by [justin808](https://github.com/justin808).
+  - When deploying to environments like Heroku staging with `RAILS_ENV=staging`, shakapacker would crash with `undefined method 'deep_symbolize_keys' for nil:NilClass`
+  - **Configuration fallback:** Now properly falls back to production environment configuration (appropriate for staging)
+  - **NODE_ENV handling:** `bin/shakapacker` now automatically sets `NODE_ENV=production` for custom environments (staging, etc.)
+    - Previously: `RAILS_ENV=staging` would set `NODE_ENV=development`, breaking webpack optimizations
+    - Now: `RAILS_ENV` in `[development, test]` uses that value for `NODE_ENV`, everything else uses `production`
+  - Logs informational message when falling back to help with debugging
+  - This ensures shakapacker works with any Rails environment even if not explicitly defined in shakapacker.yml
+  - Fixes [#663](https://github.com/shakacode/shakapacker/issues/663)
 
 ## [v9.1.0] - October 8, 2025
 

docs/deployment.md

@@ -3,8 +3,6 @@
 Shakapacker hooks up a new `shakapacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`.
 If you are not using Sprockets `shakapacker:compile` is automatically aliased to `assets:precompile`.
 
-```
-
 ## Heroku
 
 In order for your Shakapacker app to run on Heroku, you'll need to do a bit of configuration before hand.
@@ -19,13 +17,59 @@ git push heroku master
 
 We're essentially doing the following here:
 
-* Creating an app on Heroku
-* Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
-* Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
-* Pushing your code to Heroku and kicking off the deployment
+- Creating an app on Heroku
+- Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
+- Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
+- Pushing your code to Heroku and kicking off the deployment
 
 Your production build process is responsible for installing your JavaScript dependencies before `rake assets:precompile`. For example, if you are on Heroku, the `heroku/nodejs` buildpack must run **prior** to the `heroku/ruby` buildpack for precompilation to run successfully.
 
+### Custom Rails Environments (e.g., staging)
+
+**Key distinction:**
+
+- **RAILS_ENV** is used to look up configuration in `config/shakapacker.yml`
+- **NODE_ENV** is used by your `webpack.config.js` (or `rspack.config.js`) for build optimizations
+
+**Good news:** As of this version, `bin/shakapacker` automatically sets `NODE_ENV=production` for custom environments like staging:
+
+```bash
+# NODE_ENV automatically set to 'production' for staging
+RAILS_ENV=staging bin/shakapacker
+
+# Also works with rake task
+RAILS_ENV=staging bundle exec rails assets:precompile
+```
+
+**How it works:**
+
+- `RAILS_ENV=development` → `NODE_ENV=development`
+- `RAILS_ENV=test` → `NODE_ENV=test`
+- `RAILS_ENV=production` → `NODE_ENV=production`
+- Any other custom env → `NODE_ENV=production`
+
+**Configuration fallback:**
+
+You don't need to add custom environments to your `shakapacker.yml`. Shakapacker automatically falls back to production-like defaults:
+
+1. First, it looks for the environment you're deploying to (e.g., `staging`)
+2. If not found, it falls back to `production` configuration
+
+This means staging environments automatically use production settings (compile: false, cache_manifest: true, etc.).
+
+**Optional: Staging-specific configuration**
+
+If you want different settings for staging, explicitly add a `staging` section:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+  # Staging-specific overrides (e.g., different output path)
+  public_output_path: packs-staging
+```
+
 ## Nginx
 
 Shakapacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
@@ -117,10 +161,10 @@ namespace :deploy do
   desc "Run rake js install"
   task :js_install do
     require "package_json"
-    
+
     # this will use the package manager specified via `packageManager`, or otherwise fallback to `npm`
     native_js_install_command = PackageJson.read.manager.native_install_command(frozen: true).join(" ")
-    
+
     on roles(:web) do
       within release_path do
         execute("cd #{release_path} && #{native_js_install_command}")

docs/troubleshooting.md

@@ -23,6 +23,7 @@
    ```
 
 ## Incorrect peer dependencies
+
 Shakapacker uses peer dependencies to make it easier to manage what versions are being used for your app, which is especially
 useful for patching security vulnerabilities. However, not all package managers will actually enforce these versions - notably,
 Yarn will omit a warning rather than erroring if you forget to update a peer dependency:
@@ -32,6 +33,7 @@ warning " > shakapacker@6.1.1" has incorrect peer dependency "compression-webpac
 ```
 
 This omission resulted in an error in the browser:
+
 ```
 Failed to load resource: net::ERR_CONTENT_DECODING_FAILED
 ```
@@ -40,6 +42,40 @@ The error was caused by an old version of the peer dependency `webpack-compressi
 
 So, be sure to investigate warnings from `yarn install`!
 
+## NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+
+If you see this error during deployment (especially on Heroku with a staging environment):
+
+```
+NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+  from shakapacker/configuration.rb:XXX:in 'load'
+```
+
+This happens when deploying to a custom Rails environment (like `staging`) that isn't explicitly defined in your `config/shakapacker.yml` file.
+
+**Solution:** This was fixed in Shakapacker v9.1.1+. Upgrade to the latest version:
+
+```ruby
+# Gemfile
+gem 'shakapacker', '~> 9.1'
+```
+
+After upgrading, Shakapacker will automatically fall back to sensible defaults when your environment isn't defined:
+
+1. First tries your environment (e.g., `staging`)
+2. Falls back to `production` configuration
+
+**Alternative:** If you can't upgrade immediately, explicitly add your environment to `config/shakapacker.yml`:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+```
+
+See the [deployment guide](./deployment.md#custom-rails-environments-eg-staging) for more details.
+
 ## ENOENT: no such file or directory - node-sass
 
 If you get the error `ENOENT: no such file or directory - node-sass` on deploy with
@@ -54,7 +90,7 @@ thing, like Heroku.
 
 However, if you get this on local development, or not during a deploy then you
 may need to rebuild `node-sass`. It's a bit of a weird error; basically, it
-can't find the `node-sass` binary.  An easy solution is to create a postinstall
+can't find the `node-sass` binary. An easy solution is to create a postinstall
 hook to ensure `node-sass` is rebuilt whenever new modules are installed.
 
 In `package.json`:
@@ -67,19 +103,18 @@ In `package.json`:
 
 ## Can't find hello_react.js in manifest.json
 
-* If you get this error `Can't find hello_react.js in manifest.json`
-when loading a view in the browser it's because webpack is still compiling packs.
-Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
-however since this file is generated after packs are compiled by webpack. So,
-if you load a view in browser whilst webpack is compiling you will get this error.
-Therefore, make sure webpack
-(i.e `./bin/shakapacker-dev-server`) is running and has
-completed the compilation successfully before loading a view.
-
+- If you get this error `Can't find hello_react.js in manifest.json`
+  when loading a view in the browser it's because webpack is still compiling packs.
+  Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
+  however since this file is generated after packs are compiled by webpack. So,
+  if you load a view in browser whilst webpack is compiling you will get this error.
+  Therefore, make sure webpack
+  (i.e `./bin/shakapacker-dev-server`) is running and has
+  completed the compilation successfully before loading a view.
 
 ## throw er; // Unhandled 'error' event
 
-* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+- If you get this error while trying to use Elm, try rebuilding Elm. You can do
   so with a postinstall hook in your `package.json`:
 
 ```json
@@ -90,9 +125,9 @@ completed the compilation successfully before loading a view.
 
 ## webpack or webpack-dev-server not found
 
-* This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
+- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
 
-* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+- If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
 
 ```bash
 bundle config --delete bin
@@ -137,6 +172,7 @@ chmod +x $HOME/your_rails_app/node_modules/.bin/elm-make
 ```
 
 ## Rake assets:precompile fails. ExecJS::RuntimeError
+
 This error occurs because you are trying to minify by `terser` a pack that's already been minified by Shakapacker. To avoid this conflict and prevent appearing of `ExecJS::RuntimeError` error, you will need to disable uglifier from Rails config:
 
 ```ruby
@@ -152,10 +188,11 @@ Rails.application.config.assets.js_compressor = Uglifier.new(harmony: true)
 ### Angular: WARNING in ./node_modules/@angular/core/esm5/core.js, Critical dependency: the request of a dependency is an expression
 
 To silent these warnings, please update `config/webpack/webpack.config.js`:
+
 ```js
-const webpack = require('webpack')
-const { resolve } = require('path')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { resolve } = require("path")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
@@ -192,6 +229,7 @@ Thus ProvidePlugin manages build-time dependencies to global symbols whereas the
 **You don't need to assign dependencies on `window`.**
 
 For instance, with [jQuery](https://jquery.com/):
+
 ```diff
 // app/javascript/entrypoints/application.js
 
@@ -200,19 +238,20 @@ For instance, with [jQuery](https://jquery.com/):
 ```
 
 Instead do:
+
 ```js
 // config/webpack/webpack.config.js
 
-const webpack = require('webpack')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
     new webpack.ProvidePlugin({
-      $: 'jquery',
-      jQuery: 'jquery',
+      $: "jquery",
+      jQuery: "jquery"
     })
-  ],
+  ]
 })
 ```
 
@@ -225,7 +264,7 @@ application is using your staging `config.asset_host` host when using
 
 This can be fixed by setting the environment variable `SHAKAPACKER_ASSET_HOST` to
 an empty string where your assets are compiled. On Heroku this is done under
-*Settings* -> *Config Vars*.
+_Settings_ -> _Config Vars_.
 
 This way shakapacker won't hard-code the CDN host into the manifest file used by
 `javascript_pack_tag`, but instead fetch the CDN host at runtime, resolving the
@@ -243,6 +282,7 @@ In order to generate the storage path, we rely on the filename that's [provided
 This usually works out of the box. There's a potential problem however, if you use the [context setting](https://webpack.js.org/configuration/entry-context/#context) in your webpack config. By default this is set to current Node working directory/project root.
 
 If you were to override it like:
+
 ```
 {
   context: path.resolve(__dirname, '../../app/javascript')
@@ -252,12 +292,14 @@ If you were to override it like:
 Then the filename available in the rule generator will be relative to that directory.
 
 This means for example:
+
 - a static asset from `node_modules` folder could end up being referenced with path of `../../node_modules/some_module/static_file.jpg` rather than simply `node_modules/some_module/static_file.jpg`.
 - a static asset in one of the `additional_paths`, example `app/assets/images/image.jpg`, would end up being referenced with path of `../assets/images/image.jpg`.
 
 Those paths are later passed to [output path generation in the rule](https://github.com/shakacode/shakapacker/blob/e52b335dbabfb934fe7d3076a8322b97d5ef3470/package/rules/file.js#L25-L26), where we would end up with a path like `static/../../node_modules/some_module/static_file.jpg`, resulting in the file being output in a location two directories above the desired path.
 
 You can avoid this by:
+
 - not using overridden `context` in your webpack config, if there's no good reason for it.
 - using custom Webpack config to modify the static file rule, following a similar process as outlined in the [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/main/README.md#webpack-configuration) section of the readme.
 

lib/shakapacker.rb

@@ -7,6 +7,9 @@ module Shakapacker
   extend self
 
   DEFAULT_ENV = "development".freeze
+  # Environments that use their RAILS_ENV value for NODE_ENV
+  # All other environments (production, staging, etc.) use "production" for webpack optimizations
+  DEV_TEST_ENVS = %w[development test].freeze
 
   def instance=(instance)
     @instance = instance
@@ -24,6 +27,13 @@ def with_node_env(env)
     ENV["NODE_ENV"] = original
   end
 
+  # Set NODE_ENV based on RAILS_ENV if not already set
+  # - development/test environments use their RAILS_ENV value
+  # - all other environments (production, staging, etc.) use "production" for webpack optimizations
+  def ensure_node_env!
+    ENV["NODE_ENV"] ||= DEV_TEST_ENVS.include?(ENV["RAILS_ENV"]) ? ENV["RAILS_ENV"] : "production"
+  end
+
   def ensure_log_goes_to_stdout
     old_logger = Shakapacker.logger
     Shakapacker.logger = Logger.new(STDOUT)

lib/shakapacker/configuration.rb

@@ -255,7 +255,21 @@ def load
       rescue ArgumentError
         YAML.load_file(config_path.to_s)
       end
-      symbolized_config = config[env].deep_symbolize_keys
+
+      # Try to find environment-specific configuration with fallback
+      # Fallback order: requested env → production
+      if config[env]
+        env_config = config[env]
+      elsif config["production"]
+        log_fallback(env, "production")
+        env_config = config["production"]
+      else
+        # No suitable configuration found - rely on bundled defaults
+        log_fallback(env, "none (will use bundled defaults)")
+        env_config = nil
+      end
+
+      symbolized_config = env_config&.deep_symbolize_keys || {}
 
       return symbolized_config
     rescue Errno::ENOENT => e
@@ -280,7 +294,10 @@ def defaults
         rescue ArgumentError
           YAML.load_file(path)
         end
-        HashWithIndifferentAccess.new(config[env] || config[Shakapacker::DEFAULT_ENV])
+        # Load defaults from bundled shakapacker.yml (always has all environments)
+        # Note: This differs from load() which reads user's config and may be missing environments
+        # Fallback to production ensures staging and other custom envs get production-like defaults
+        HashWithIndifferentAccess.new(config[env] || config["production"])
       end
     end
 
@@ -289,4 +306,13 @@ def relative_path(path)
 
       path
     end
+
+    def log_fallback(requested_env, fallback_env)
+      return unless Shakapacker.logger
+
+      Shakapacker.logger.info(
+        "Shakapacker environment '#{requested_env}' not found in #{config_path}, " \
+        "falling back to '#{fallback_env}'"
+      )
+    end
 end

lib/shakapacker/rspack_runner.rb

@@ -6,7 +6,7 @@ module Shakapacker
   class RspackRunner < Shakapacker::Runner
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
       new(argv).run
     end
 

lib/shakapacker/runner.rb

@@ -24,7 +24,7 @@ class Runner
     ].freeze
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
 
       # Create a single runner instance to avoid loading configuration twice.
       # We extend it with the appropriate build command based on the bundler type.