Troubleshooting

Most problems after installing or updating an add-on fall into one of these causes:

• stale caches
• a theme that overrides templates
• a conflict with another add-on
• a server error that only shows up in the logs

Work through this page from top to bottom.

Clear the cache

CS-Cart caches data, compiled Smarty templates and the combined CSS/JS bundles. After installing, updating or reconfiguring an add-on, clear the cache first.

Method	What it clears
Admin gear menu (top right) → Clear cache	Data cache and template cache
admin.php?cc	Data/registry cache, static cache, CSS/JS bundles
admin.php?ctpl	Compiled templates
admin.php?cc&ctpl	Both. Use this one when in doubt.
admin.php?ct	Generated image thumbnails
Delete var/cache/* on the server	Everything. Only for the default file cache backend.

You can add the parameters to any admin URL, e.g. admin.php?dispatch=addons.manage&cc&ctpl. If you renamed admin.php, use your custom admin script name.

Note

?cc and ?ctpl only work in the admin panel. They’re ignored on the storefront and in the Multi-Vendor vendor panel unless developer mode is on.

Also clear your browser cache (or use a private window) and any CDN or reverse proxy in front of your store, such as Cloudflare, Varnish or nginx fastcgi_cache. These keep serving old CSS and JS until you purge them.

Changes don’t appear on the storefront

1. Clear the cache as described above.
2. Check the add-on status. It must be Active in Add-ons → Manage add-ons.
3. Check the block. If the feature is a block, make sure it’s placed in Design → Layouts on the right layout and location, and that the block status is active.
4. Check the theme. On installation, CS-Cart copied our templates into every theme that existed at the time. If you installed a new theme afterwards, it won’t have them. Reinstall the add-on, or copy var/themes_repository/responsive/templates/addons/kv_<addon>/ into design/themes/<your_theme>/templates/addons/kv_<addon>/. Do the same for css/.
5. Check theme overrides. Some themes replace whole templates, such as the product page or the cart, and skip the template hooks our add-ons rely on. If a feature shows up with the default Responsive theme but not with yours, the theme is the cause. Send us the theme name and we’ll help.

Enable developer mode

Developer mode shows PHP errors on screen and lets you use the cache-clearing parameters everywhere. Only enable it on staging, or for a few minutes on production.

Create or edit local_conf.php in the CS-Cart root (next to config.local.php):

<?php
define('DEVELOPMENT', true);
// define('DEBUG_MODE', true); // also show the debug toolbar on every page

Remove the file, or comment out the lines, when you’re done.

The built-in debugger

Open any admin page with ?debug added to the URL, or press Ctrl+Alt+D. The debugger panel shows:

• SQL queries and their timings
• the templates used to render the page
• request data
• configuration values
• cache statistics

It helps you find slow queries and see which template is rendering a block.

Error logs

Look in these places, in this order:

1. Administration → Logs. CS-Cart’s own log. To log more events, go to Settings → Logging and enable Requests temporarily to see API and payment gateway calls.
2. PHP error log. Its location depends on your host, e.g. /var/log/php*-fpm.log, error_log in the CS-Cart root, or your hosting panel’s Logs section. Check the error_log setting in phpinfo (gear menu → phpinfo).
3. Web server log. The nginx or Apache error.log shows fatal errors that cause a blank page or HTTP 500.
4. Upgrade logs. For update problems, see var/upgrade/*_log.txt.
5. Browser console. Press F12 → Console to see JavaScript errors. A JS error from any add-on can stop the scripts of every other add-on on that page.

Include the relevant log lines when you contact support.

Find add-on conflicts

If a feature misbehaves only with certain add-ons installed:

1. Make a staging copy of the store.
2. On the staging copy, disable (don’t uninstall) third-party add-ons one at a time, clearing the cache each time, until the problem disappears.
3. The last add-on you disabled is the likely source of the conflict. Typical causes:
   • Two add-ons override the same template. Only one override can win, and CS-Cart decides which by add-on priority.
   • Two add-ons change the same data in a PHP hook.
   • A JavaScript error in one add-on stops scripts on the page.
4. Send us the name and version of the conflicting add-on. Our add-ons don’t modify core files and only use hooks, so most conflicts can be fixed on our side.

Common errors

Error	Cause and fix
Blank page / HTTP 500 after install	A PHP fatal error. Enable developer mode or check the PHP error log. Often the PHP version is outside the supported range.
“Access denied” in the vendor panel	The vendor’s user group lacks the add-on’s privilege. See Multi-Vendor notes.
Text shows as kv_addon.some_key	A language variable is missing for the current language. Clear the cache. If that doesn’t help, reinstall the add-on’s language pack, or add the translation in Administration → Languages → Translations.
Settings page is empty	The template cache is stale. Run admin.php?ctpl.
Styles look broken	A CDN or browser is caching old CSS. Run admin.php?cc and purge the CDN.

Still stuck?

Contact support and include:

• your CS-Cart version and edition
• your PHP version
• the add-on version
• your theme
• the steps to reproduce the problem
• any log lines

Staging access speeds things up a lot.