Troubleshooting

Solving theme display problems

The quickest way to fix most theme display issues, is to shut down and restart Sublime Text.

If that doesn't sort things out, try some of the troubleshooting steps below.

Quick tips for theme issues

• Shutdown and restart Sublime Text
• Check the theme hasn't been added to the ignored_packages list
• Confirm the theme name is correctly specified in your settings file
• Make sure you are using the correct theme file for your Sublime Text version (ST2 / ST3)
• For manual installs check the theme was copied to the correct folder location
• Check the Sublime Text console for errors when loading the theme
• Confirm that you have only one copy of the theme installed
• Make sure you are using the theme configuration setting, not the colour scheme setting, to specify the theme

What does a theme issue look like

Below are some real examples of theme display issues that have been submitted to the issue tracker over time for Soda Theme.

Restart Sublime Text

The quickest way to solve most problems is to restart Sublime Text.

When you change or update your theme, Sublime Text does its best to dynamically load and apply the new theme. If during this process, Sublime Text has trouble cleanly reloading assets or updating the UI parameters to the new theme settings, you may see visual rendering artefacts where theme backgrounds are not redrawn or updated correctly via the dynamic reload mechanism.

This typically presents as missing assets, with areas of the UI displaying a red or black background, or no background at all. It can also cause distorted and corrupted visual rendering.

After changing or updating a UI theme, a simple way to ensure the theme is applied properly, is to shut down and restart Sublime Text

Check ignored packages settings

A second area to check is your Ignore Packages list in your User Preferences file.

Sublime Text will move a package into this area temporarily when updating the package. In some scenarios, it will fail to move the package back out of the ignored list when the update is complete, causing the package to not be available for use.

Check that the theme is not in the ignored packages list

Open your User Preferences file Sublime Text -> Preferences -> Settings - User, and remove any entry for Soda Theme if one exists in the ignored packages array.

Example of incorrect settings

"ignored_packages":
[
	"Theme - Soda"
]

Check for console errors

Another good debugging technique is to open the Sublime console CTRL + ` when loading or changing a theme and look for any errors. If Sublime can't find assets related to the theme, or there is another theme related issue, you may see useful output in the console that helps resolve the issue.

Open the Sublime console with CTRL + ` and look for theme related asset loading errors

Check theme declaration

Check to make sure that you have used the "theme" property for activating the theme in your Sublime Text -> Preferences -> Settings - User file (or other configuration files), and not accidentally used the incorrect "color_scheme" property.

Also ensure that you do not set your editors syntax highlighting colour scheme to use any of the themes internal colour scheme files. These files are referenced by the theme itself and should not be configured or referenced in your settings.

The following declaration (in this case, for Soda Light) is the correct way to configure the theme:

{
    "theme": "Soda Light.sublime-theme"
}

For Sublime Text 3, the theme configuration is:

{
    "theme": "Soda Light 3.sublime-theme"
}

Confirm installation location

If you have copied the Soda Theme folder to the wrong location, the theme will not be able to load its assets and you will see red or black backgrounds for all components.

To fix this issue, make sure the theme is located inside the Sublime Text Packages directory with the correct folder name. You can find the Packages directory by using the menu item Preferences -> Browse Packages...

Check for only one copy of the theme

Some users reporting rendering issues have found that there was an older copy of the theme either in their Packages/User folder or another location. Having this additional, older version was causing Sublime Text to load both theme copies and mix the rules together, causing odd visual results.

Check that there is only one copy of the theme files and that they are in the correct location