Troubleshooting theme extensions
This page is for designers and administrators when a theme does not behave. Find the symptom, read the cause, apply the fix. For problems inside templates, see Debugging a design and Common template mistakes.
| You see | Likely cause | Fix |
|---|---|---|
| The site shows the standard design | The extension is not active, or does not register its design | Activating a theme, Registering the design; clear the INI cache |
| The administration suddenly uses the theme | The theme sets SiteDesign globally | Move SiteDesign to the site's siteaccess (The design settings a theme ships) |
A new .tpl file is ignored; the page is empty | The template override cache still has the old list | php bin/php/ezcache.php --clear-id=template-override --allow-root-user |
| Another theme's template wins | Loading order | Loading order and which theme wins |
| The About page shows a dash for the version | ezinfo.php or extension.xml lacks it, or extension.xml has another value | Keeping every version field in sync |
Composer puts the theme into extension/my-theme | extra.ezpublish-legacy-extension-name is missing | The Composer installer and the folder name |
| "Unknown template operator" for the theme's operator | autoloads/eztemplateautoload.php or ExtensionAutoloadPath[] is missing | Template operators in a theme |
| A new PHP class is not found | Autoload array not regenerated, or the PHP service not reloaded | php bin/php/ezpgenerateautoloads.php -e, then reload PHP-FPM or Velocity |
| Theme texts stay in English | TranslationExtensions[] missing, or the translation cache | Translations in a theme |
| A changed stylesheet does not reach the browser | The packed stylesheet is cached | Clear the packer and template-block caches (Packer cache and deploy); hard-reload the browser |
| Exporting the theme is refused | Exporting is off, or the secret check found something | Exporting an extension as a package, The secret check |
| Upload of your package: "already exists" | A package of that name is on that installation | Remove the old one there, or rename yours |
A general routine
- Clear the caches:
php bin/php/ezcache.php --clear-all --allow-root-user. - Regenerate the autoloads:
php bin/php/ezpgenerateautoloads.php -e. - Reload the PHP service that serves the site.
- Turn on template debugging for your own IP address and read the path comments.
- Check
var/log/error.logand the site's debug output.
If the problem remains and you believe it is a bug in Exponential, report it (When something goes wrong).
Related pages
- Checklist: the theme extension is ready
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.