The Single-Table Inheritance Mechanism Failed to Locate the Subclass

Introduction

This article explains the Single-Table Inheritance (STI) error that can occur in Easy8 or Redmine environments, especially when working with custom plugins or database migrations. Understanding the cause and solution for this error can help administrators resolve system failures related to missing class types.

Target Audience

Administrator

Understanding the Error

Error Message

ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'EpmEasyButtons'. This error is raised because the column 'type' is reserved for storing the class in case of inheritance.)

Cause

Rails uses the type column to implement single-table inheritance (STI).
If a plugin or class like EpmEasyButtons is missing but still referenced in the database, Rails cannot resolve it, raising the error.

Typical Triggers

Plugin files were deleted without properly uninstalling the plugin.
Plugin migrations were not reversed before file removal.
Database records still refer to a removed subclass.

How to Fix It

1. Properly Uninstall Plugins

Never delete plugin files directly. Use the following commands:

For Easy Plugins:

bundle exec rake easyproject:uninstall:all_plugins RAILS_ENV=production

For Redmine Plugins:

bundle exec rake redmine:plugins:migrate RAILS_ENV=production VERSION=0 NAME=plugin_name

Example:

bundle exec rake redmine:plugins:migrate RAILS_ENV=production VERSION=0 NAME=redmine_agile

2. Manually Remove Orphaned Records

If the plugin files are already deleted and the error persists:

Open the Rails console:
```
rails c production
```

Run:

EasyPageModule.all

If the error is triggered, delete the orphaned records:

EasyPageModule.where(:type => 'EpmEasyButtons').delete_all

Repeat the command until there is no error.

3. Check Other Tables

This issue can occur in other STI tables:

EasyQuery
CustomField
EasyRakeTask
Attachment

Use the same technique to locate and remove broken references in those tables.

Conclusion

STI errors caused by orphaned class references can disrupt page loading and application behavior. Prevent these issues by properly uninstalling plugins before removing files. If problems persist, use the Rails console to clean up database entries referencing missing classes.