This guide explains the basics of how to troubleshoot issues with cPanel styles.
This document lists appropriate test steps for most custom code, and helpful information to troubleshoot common problems. Make certain that you evaluate the testing requirements of your own code, and allow its functionality to determine the appropriate steps.
cPanel Technical Support cannot always assist third-party developers with problems that relate to custom code. For this reason, always test your projects thoroughly before you attempt to use them on production servers.
Because the testing requirements of custom code differ, this document begins with the assumption that you have already discovered problems.
The cPanel interface uses account permissions and ownership to determine the available styles for each cPanel user.
- All cPanel accounts on the server can access the
rootuser's styles, which must exist in the
- Only cPanel accounts that a specific reseller owns can view that reseller's styles, which must exist in the
resellerrepresents the reseller's username.
When you upload styles via WHM's Customization interface (WHM >> Home >> cPanel >> Customization), the system uploads the style to the correct directory for the authenticated user.
For example, if the bob reseller uploads the
stylish style via the WHM interface, the system automatically stores it in the
Unless you set a style as the global default style, or as the default style for a reseller, the style will not display by default. Check to ensure that you have properly applied the style to the account that you wish to view it in.
- For more information about how to apply the style as the default style, read our Customization and Guide to cPanel Interface Customization - Apply Styles documentation.
To apply a style to a specific account through the cPanel interface, perform the following steps:
- Log in to cPanel as the desired user.
- Navigate to cPanel's Change Style interface (cPanel >> Home >> Preferences >> Change Style).
- Click Apply for the desired style.
To apply a style to a specific account through the command line, perform the following steps:
- Log in to the server via SSH as the desired user.
Run the following command, where
usernamerepresents the cPanel account's username, and
path_to_stylerepresents the absolute path to the style that you wish to apply:
ln -s path_to_style /home/username/var/cpanel/styled/current_style
For example, to apply the
/var/cpanel/customizations/styled/mystylestyle for the username user, run the following command:
ln -s /var/cpanel/customizations/styled/mystyle /home/username/var/cpanel/styled/current_style
When you attempt to upload a style in WHM's Customization interface (WHM >> Home >> cPanel >> Customization), the interface returns an error and does not upload the style.
This problem occurs when WHM detects a problem with the style that you attempted to upload.
- Make certain that the style file that you attempt to upload is a valid
- Make certain that the style's files exist within a directory within the style tarball.
- Make certain that the style tarball contains either a
styles.cssfile or a
For more information about all of these requirements, read our Guide to cPanel Interface Customization - cPanel Style Development documentation.
After you upload a style via the command line, the style does not function properly.
Many problems may occur if the style's file permissions are not correct. Check to ensure that the style directory, subdirectories, and files all use
A style that should contain a preview image displays the cPanel-provided filler preview image instead in cPanel's Change Style interface (cPanel >> Home >> Preferences >> Change Style).
This problem generally occurs due to bad file permissions or file types:
- Check to ensure that the preview image file uses
- Check to ensure that the preview image file is a