Recently, we have had issues migrating doctypes after a rename or removal. It seems to keep a reference all over the system. The process of removal has been mixed but successful.
Summary
The issue was that the Python class name didn't match Frappe's naming convention. For a DocType named "SID Color Scheme", Frappe expects the class name to be SIDColorScheme (removing spaces and using PascalCase), not ColorScheme.
Changes made:
Renamed the Python class from ColorScheme to SIDColorScheme in sid_color_scheme.py
Updated the JavaScript method reference from ColorScheme.apply_theme to SIDColorScheme.apply_theme in sid_color_scheme.js
Result:
The DocType now migrates successfully without being marked as orphaned
The DocType exists in the database and is properly recognized by Frappe
All file references are correct
You can now use the "SID Color Scheme" DocType without migration issues. The theming system should work as expected.
Common causes of orphaned DocTypes in Frappe:
Common causes of orphaned DocTypes
1. DocType renamed without proper migration
Problem: Renamed the DocType JSON but didn’t rename the folder/files or update all references.
Example: Renamed "Color Scheme" to "SID Color Scheme" but kept the folder as color_scheme/.
Fix: Rename the folder, update all Python/JS imports, and run bench migrate.
2. DocType deleted but records remain
Problem: Deleted the DocType definition but records still exist in the database.
Fix: Delete records first, then remove the DocType, or use frappe.delete_doc() with force=1.
3. Child DocType (Table) not found
Problem: A parent DocType references a child DocType (Table field) that doesn’t exist.
Example: SID Settings has options: "Queue SLA Configuration" but the child DocType is missing.
Fix: Ensure child DocTypes exist and are properly named.
4. Module path mismatch
Problem: Python class name doesn’t match Frappe’s naming convention.
Example: DocType "SID Color Scheme" should have class SIDColorScheme, not ColorScheme.
Fix: Match the class name to the DocType name (remove spaces, PascalCase).
5. File structure mismatch
Problem: Folder/file names don’t match the DocType name.
Example: DocType "SID Color Scheme" should be in sid_color_scheme/ folder with sid_color_scheme.py.
Fix: Use frappe.utils.scrub() to convert DocType name to folder name.
6. DocType moved between apps
Problem: DocType was moved from one app to another but database records still reference the old app.
Fix: Update all references and run proper migration scripts.
7. DocType marked as custom but files exist
Problem: DocType exists in files but is marked as custom: 1 in the database, or vice versa.
Fix: Ensure custom field matches reality (standard DocTypes have files, custom ones don’t).
How Frappe detects orphaned DocTypes
During bench migrate, Frappe:
Scans all apps for DocType JSON files.
Compares with database DocType records.
Marks as orphaned if:
Found in DB but no matching JSON file, or
Found in DB but module path doesn’t resolve.
Prevention tips
Always use bench migrate after creating/renaming DocTypes.
Keep folder names in sync with DocType names (use frappe.utils.scrub()).
Match class names to DocType names (PascalCase, no spaces).
Ensure child DocTypes exist before referencing them.
Use bench --site [site] console to verify DocType exists before migration.
Your current situation
No orphaned DocTypes found. The child tables (Queue SLA Configuration and Notification Recipient) exist and are properly linked to SID Settings. The earlier "SID Color Scheme" issue was a class name mismatch, which is resolved.
If you see orphaned DocTypes again, check:
Folder/file names match the DocType name
Python class name matches the DocType name
All imports use the correct module path
Child DocTypes exist and are properly referenced
The system looks good now.