Troubleshoot Legacy Ruby Installations

Last modified: July 13, 2022



We deprecated the legacy Ruby codebase in cPanel & WHM version 66. We will not support any applications you create with the following interfaces:

  • cPanel’s Ruby on Rails interface (cPanel » Home » Software » Ruby on Rails).

  • cPanel’s RubyGems interface (cPanel » Home » Software » RubyGems).

  • The Ruby Gem installer feature in WHM’s Module Installers interface (WHM » Home » Software » Module Installers).

To install Ruby and create Ruby web applications in cPanel & WHM version 66 and later, follow the directions in our How to Create Ruby Web Applications documentation.

This document outlines several problems that you may experience with your Ruby installation in cPanel & WHM version 64 and earlier.

Ruby on Rails® web server port

Ruby on Rails uses its own web server, which must run on an alternate port. This causes an issue if you run a firewall on your system.


Ensure that you have opened each Ruby application’s port in your firewall. We recommend that you only open the range of ports that are necessary to access each application (for example, if you run six Ruby applications, open ports 12001 through 12006 on the firewall).

Unavailable RubyGems repository

Occasionally, the RubyGems repository is unavailable. If the RubyGems repository is unavailable during the installation process, run the /usr/local/cpanel/scripts/installruby script again.


For more information, read the Ruby documentation.

Mongrel-specific errors

To troubleshoot Mongrel-specific errors, review the /log/mongrel.log file.

  • If the errors indicate uninstalled gems, install them with the gem install name command, where name represents the gem name.

  • If the errors indicate the wrong version of gems, run the gem uninstall command, and then reinstall the correct gem version.

You can also restart the Mongrel server manually to resolve other issues. To do this, run the following command:

mongrel_rails start -p -d -e production -P log/

Run this command from the Ruby on Rails application’s base directory as the user who owns the Ruby application.

Other problems

If you encounter an unidentified problem, you can perform the following actions to troubleshoot the issue:

  • Use Ruby’s built-in tools to diagnose the problem. cPanel & WHM uses the standard set of Ruby on Rails tools.

  • Check the /usr/local/cpanel/logs/error_log file and the /log/mongrel.log file for Ruby-related errors.

  • Check for application-specific errors in the /log/mongrel.log file.

Additional Documentation