Troubleshooting

Troubleshooting & FAQ

Common Issues

Colors not updating when switching themes

Cause: The binder may not be subscribed to theme events.

Solutions:

• Make sure the binder component is enabled (checkbox in Inspector)
• Check that Theme.Instance is not null — open Window > Unity-Theme to ensure the database exists
• Verify the binder's color GUID matches an existing color in the database

Binder shows "Color not found" error

Cause: The color GUID stored in the binder doesn't match any color in the database.

Solutions:

• Select the binder in the Inspector and re-assign the color from the dropdown
• If you migrated from v2, ensure you copied the GUIDs correctly (see Migration from v2)
• Check that Assets/Resources/Unity-Theme-Database.json exists and contains the expected colors

Changes not persisting after closing Unity

Cause: The database may not be saving properly.

Solutions:

• Ensure Assets/Resources/Unity-Theme-Database.json exists in your project
• Make changes through the Window > Unity-Theme editor window (not just via code)
• Runtime C# API changes are session-only and do not persist to disk

Pink/magenta color on Renderer binders

Cause: The shader property name doesn't match the material's actual property.

Solutions:

• If using URP/HDRP Lit materials, enable "Use Custom Property" on the binder and set it to _BaseColor instead of the default _Color
• Check your shader's property names in the material Inspector (click the gear icon)
• Common property names:
  • Built-in RP: _Color
  • URP Lit: _BaseColor
  • HDRP Lit: _BaseColor
  • Unlit: _Color or _BaseColor

Custom binder not appearing in Add Component menu

Cause: Missing or incorrect [AddComponentMenu] attribute.

Solutions:

• Add [AddComponentMenu("Theme/YourBinder Name")] to your class
• Ensure the class is public and not abstract
• Make sure there are no compile errors in your script
• Check that the script file name matches the class name

Binder target is null

Cause: The target component is on a different GameObject or was destroyed.

Solutions:

• The binder auto-detects the target component on the same GameObject. Make sure the target component (e.g., Image, TextMeshPro) is on the same GameObject as the binder
• Use a Required variant binder (e.g., ImageColorBinderRequired) to ensure the component exists

FAQ

Can I have multiple databases?

No. Unity-Theme uses a single database file at Assets/Resources/Unity-Theme-Database.json. All themes and colors are managed in this one file.

Can I switch themes at runtime?

Yes. Use the C# API:

Theme.Instance.CurrentThemeName = "Dark";
// or
Theme.Instance.CurrentThemeIndex = 1;

All binders update automatically when the theme changes.

Do runtime color changes persist?

No. Changes made via the C# API at runtime are session-only. The JSON database is only saved in the Editor. If you need runtime persistence, save the theme index to PlayerPrefs and restore it on startup.

Can I use Unity-Theme with Addressables?

Unity-Theme loads its database from Resources/, so it works out of the box without Addressables. The binder components reference colors by GUID strings, not by asset references, so they are compatible with any loading strategy.

Can I add colors at runtime?

Yes. Use Theme.Instance.AddColor("MyColor", "#FF0000") to add colors at runtime. However, you'll need to manually set up binders or subscribe to events to use them — the Inspector dropdown is editor-only.

How do I set different alpha per binder?

Enable Override Alpha on the binder in the Inspector. This lets each binder use the same theme color but with a different alpha value. Useful for backgrounds, overlays, and disabled states.

Does Unity-Theme support Unity 6?

Yes. Unity-Theme is tested against Unity 6000.3.9f1 (Unity 6) in the CI pipeline for editmode, playmode, and standalone builds.

Can I use the same color in multiple binders?

Yes. Multiple binders can reference the same named color. When the color changes (theme switch or API call), all binders update.

See Also

• Getting Started — Installation and first steps
• C# API Reference — Full API documentation
• Data Model & Database — Understanding the database format
• Report an issue on GitHub