Red Hat Satellite 6.17 upgrade fails with error expected file /usr/share/foreman/lib/satellite/version.rb to define constant Satellite::Version, but didn't (Zeitwerk::NameError)

Environment

• Red Hat Satellite 6.17

Issue

• The upgrade to Red Hat Satellite 6.17 fails as the foreman service fails to start with the following error:

  [ERROR ] [configure] Aug 21 17:01:41 satellite.example.com foreman[110347]: /usr/share/gems/gems/zeitwerk-2.6.18/lib/zeitwerk/loader/callbacks.rb:32:in `on_file_autoloaded': expected file /usr/share/foreman/lib/satellite/version.rb to define constant Satellite::Version, but didn't (Zeitwerk::NameError)
  

Resolution

• Move the /usr/share/foreman/lib/satellite directory to another location.

  # mv /usr/share/foreman/lib/satellite /tmp
  

• Re-run the Satellite upgrade.

  # satellite-maintain upgrade run
  

For more KB articles/solutions related to Red Hat Satellite 6.x Installation/Upgrade/Update Issues, please refer to the Red Hat Satellite Consolidated Troubleshooting Article for Red Hat Satellite 6.x Installation/Upgrade/Update Issues.

Root Cause

• The directory /usr/share/foreman/lib/satellite should not exist, as it is not part of a standard Red Hat Satellite installation.
• The upgrade fails because the Zeitwerk autoloader expects Satellite::Version in /usr/share/foreman/lib/satellite/version.rb.

Diagnostic Steps

• The upgrade of the Red Hat Satellite server fails, and the following errors are observed:

     2025-08-21 17:01:42 [ERROR ] [configure] Systemd start for foreman failed!
     2025-08-21 17:01:42 [ERROR ] [configure] journalctl log for foreman:
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:21 satellite.example.com systemd[1]: Starting Foreman...
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:31 satellite.example.com foreman[110347]: => Booting Puma
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:31 satellite.example.com foreman[110347]: => Rails 7.0.8.7 application starting in production
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:31 satellite.example.com foreman[110347]: => Run `bin/rails server --help` for more startup options
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:39 satellite.example.com foreman[110347]: /usr/share/gems/gems/foreman_theme_satellite-14.3.3/app/models/concerns/distributor_version.rb:5: warning: already initialized constant Katello::Glue::Provider::DISTRIBUTOR_VERSION
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:39 satellite.example.com foreman[110347]: /usr/share/gems/gems/katello-4.16.0.8/app/models/katello/glue/provider.rb:3: warning: previous definition of DISTRIBUTOR_VERSION was here
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:41 satellite.example.com foreman[110347]: Exiting
     2025-08-21 17:01:42 [ERROR ] [configure] Aug 21 17:01:41 satellite.example.com foreman[110347]: /usr/share/gems/gems/zeitwerk-2.6.18/lib/zeitwerk/loader/callbacks.rb:32:in `on_file_autoloaded': expected file /usr/share/foreman/lib/satellite/version.rb to define constant Satellite::Version, but didn't (Zeitwerk::NameError)
  
     OR
  
     2026-02-27 12:37:25 [ERROR ] [configure] Feb 27 12:32:42 satellite.example.com foreman[10320]: <internal:/usr/share/rubygems/rubygems/core_ext/kernel_require.rb>:85:in `require': cannot load such file -- /usr/share/foreman/lib/satellite/version.rb (LoadError)
     2026-02-27 12:37:25 [ERROR ] [configure] Feb 27 12:32:42 satellite.example.com foreman[10320]:         from <internal:/usr/share/rubygems/rubygems/core_ext/kernel_require.rb>:85:in `require'
  

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.