Redmine Plugin Not Loading: A Safe Debugging Checklist

Start with the exact failure mode

When a Redmine plugin is not loading, avoid changing several things at once. First identify whether Redmine fails to boot, the plugin is missing from the plugin list, a migration failed, or the UI loads but the feature is absent. Each failure points to a different class of problem.

1. Verify the plugin directory name

Most Redmine plugins must be placed directly under plugins/ with the expected folder name. A nested archive like plugins/plugin-name/plugin-name/init.rb will not load. Check that the plugin has an init.rb file at the first folder level.

ls -la plugins/plugin_name
ls -la plugins/plugin_name/init.rb

2. Check Redmine, Ruby, and Rails compatibility

A plugin can be valid and still fail on the wrong Redmine version. Check the plugin README or compatibility matrix for supported Redmine versions. If you upgraded Redmine recently, test the plugin in a staging copy before changing production.

3. Run Bundler from the Redmine root

If the plugin has dependencies, run Bundler from the Redmine root, not inside the plugin folder. In Docker-based setups, run the command inside the Redmine container.

bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

4. Read the boot log, not only the browser error

The browser often shows a generic 500 page. The real error is usually in log/production.log, container logs, or the process manager output. Look for LoadError, NameError, missing constants, duplicate routes, or migration failures.

5. Clear caches and restart cleanly

After adding or removing plugins, restart the Redmine process. If assets are involved, recompile assets in production. Avoid hot-swapping plugin folders on a live process.

6. Roll back safely

If production is down, remove only the newly added plugin, restore the previous bundle state if needed, and restart. Then reproduce in staging with the same Redmine and Ruby versions.

How RedmineShop reduces this risk

Commercial RedmineShop plugins are planned to ship with compatibility notes, migration guidance, and diagnostics. For SSO/access-control needs, follow the SSO & Access Suite waitlist for release updates.