Deutsche Version

Back to overview

Custom CSS Loader: Troubleshooting

Problem: Plugin cannot be loaded (fatal error)

Cause: vendor/autoload.php is missing. This happens with a Git clone, because vendor/ is not in the repository.

Solution: Run composer install --no-dev in the plugin folder or use the release ZIP (see Installation).

Problem: CSS is not loaded

Symptoms:

• The styles have no effect.
• The page source contains no <!-- Custom CSS Loader Plugin --> block.

Check:

1. Is the plugin enabled and the Enable Custom CSS Loader option switched on?
2. Is the file in <osTicket root directory>/assets/custom/css/ and does it end in .css (lowercase)?
3. Does the name contain staff or client? Without one of them the file is ignored.
4. Is the name valid? It starts with a letter or digit and contains only letters, digits, _ and -. Blocked names appear in the PHP error log as Invalid filename blocked.
5. Is the file readable for the web server (for example chmod 644)?
6. Does the page have a </head>? Without this tag nothing is inserted.
7. Is the file in a subfolder or a symlink pointing outside? Both are not loaded.

Problem: CSS is loaded but has no effect

• Check in the browser developer tools (F12) whether the file was loaded and whether syntax errors are reported.
• osTicket styles can have a higher specificity. Add !important or a more specific selector.
• The browser may cache older versions even though the URL contains ?v= with the modification time. Do a hard reload.
• Multiple files are loaded alphabetically, later files override earlier ones.

Problem: The file appears in the wrong area

The first match wins, and staff is checked before client. A name like client-staff.css therefore counts as a staff file. Rename the file so that only one of the terms occurs.

Problem: CSS folder is not created

The web server user is not allowed to write in the osTicket root directory. Create the folder manually:

mkdir -p /path/to/osticket/assets/custom/css
chmod 755 /path/to/osticket/assets/custom/css

Problem: Demo files were not copied

The plugin only copies on activation and only if the folder contains no .css file yet. Copy the files you want from include/plugins/custom-css-loader/assets/demo/ by hand.

Frequently asked questions

Does the plugin change osTicket files?

No. The link tags are inserted into the page through output buffering.

Do I lose my CSS files when deactivating?

No. Deactivating and updating leave the assets/custom/css/ folder untouched.

Does the plugin affect the API?

No, no CSS is inserted for calls under /api/.

Which versions are required?

osTicket 1.17 or newer and PHP 8.1 or newer. The CI runs the tests with PHP 8.1 to 8.4.