Updating core files in PrestaShop often introduces underlying changes to controller variable assignments and layout architecture. When these system updates occur, your customized Smarty and Twig template overrides can silently fall out of sync with the backend logic without raising obvious fatal errors.
This disconnect frequently manifests as missing UI elements, broken hook contexts, or silent data loading failures across your storefront. Understanding how core updates alter template resolution paths helps you proactively safeguard your custom overrides from quiet breaks.
What Really Changes in a Core Update That Affects Overrides
PrestaShop core updates can break Smarty and Twig template overrides because the core changes template file paths, preprocessor syntax (moving from Smarty to Twig), or the way themes declare overrides in theme.yml. To fix this, identify which templates your overrides target, check if the parent template has been renamed or moved, and update your override files to match the new structure or migrate to Twig with proper theme inheritance. Always test overrides on a staging site after each core update, and reference the PrestaShop changelog for template-related changes.
Nothing looks wrong at first. Your module still appears in the back office, the theme still loads, and the page renders. But the customisation you built simply does not show. PrestaShop does not throw a fatal error when an override target no longer exists; it just falls back to the core template and moves on.
Core updates touch four main areas that affect overrides.
- Template file paths. PrestaShop occasionally reorganises the templates directory. A file at themes/classic/templates/catalog/product.tpl may move to a subfolder or adopt a new name. Your override still points at the old location, so it never loads.
- Template engine transitions. Older PrestaShop versions used Smarty files with the .tpl extension. Newer cores introduced Twig with the .twig extension. If a template you overrode switched engines, your Smarty override is ignored entirely.
- theme.yml declaration changes. Themes declare override mappings in the theme.yml file. Core updates can change the expected format, adding or renaming keys. A malformed declaration prevents the theme from recognising your override.
- Syntax and variable changes. Even when a file path stays identical, variables passed to a template can change. A core update might replace a variable name, merge two variables, or shift content into a sub-template. Your override still loads, but the output looks wrong or empty.
All four changes share one trait: they produce no obvious error. The core simply uses its own template because the override no longer matches the expected structure. The only reliable way to catch this is to compare your override files against the core templates after every update.
Why Your Smarty Override Stopped Working After the Update
When a Smarty override stops working after a core update, the cause is rarely a corrupted file. The core templates your override depended on have been deprecated, removed, or had their variables renamed. The override still exists on disk and loads without errors, but silently falls back to the core template because the hooks and paths it targeted no longer match.
PrestaShop's fallback logic is designed to be forgiving: if an override cannot find the expected template or variable, the system quietly uses the core file instead of throwing an exception. In a local staging environment with Smarty caching disabled and debug mode enabled, you might spot the issue quickly. On production, where cache is warm and error reporting is suppressed, the broken override can pass unnoticed for days.
Three changes in a core update typically cause this:
- Template files moved or removed. A core
.tplfile your override extended may have been relocated, renamed, or replaced. Your override points at the old path, so PrestaShop ignores it. - Smarty variables renamed or deprecated. Core updates frequently change variable names, such as replacing a flat variable with an object property or introducing a new array structure. Your override references the old variable, which now renders empty or triggers the fallback.
- Different override mechanism. Newer PrestaShop versions shift rendering logic between Smarty templates and PHP classes. An override that worked in one version may not be read the same way in a later version, even when the file structure appears identical.
Identifying the exact change requires comparing the overridden template against the current core version. Open both files side by side and check which template variables are present in the core file but missing from your override. Look specifically at {if} conditions and variable assignments: if the core template now uses a variable your override never declares, the fallback engages silently.
The most reliable diagnostic step is to enable debug mode and watch the Smarty compile directory. When a template fails to override correctly, PrestaShop often logs a notice about the missing template or variable in the server error log. Check var/logs in your PrestaShop installation after reproducing the issue on a staging copy, and search for entries mentioning your override's filename. That single log line usually reveals whether the path, the variable, or the cache is the culprit.
The Shift to Twig: When Overrides Move from Smarty .tpl to Twig .twig
The most disruptive change for template overrides comes when a core update migrates a theme from Smarty to Twig. PrestaShop moves away from the legacy Smarty engine and towards Twig for front-office rendering. For developers who have maintained .tpl files for years, the core update can make those files silently irrelevant, not because the code is wrong, but because the engine no longer reads it.
Understanding the migration path matters because it changes where you must place your override. In Smarty-based versions, you placed custom templates in the themes/yourtheme/modules folder. With the Twig transition, the template lookup order and file extensions shift,.twig and the module template directories are consulted differently by the FME Modules team and other PrestaShop partners building custom layouts.
This decoupling is intentional. PrestaShop separates the presentation layer from the business logic so that core updates do not overwrite design work. The side effect is that an override that appears perfectly valid after the update, because your module still renders, can break in production when the core template path changes underneath it.
- File extension change: Your override may sit in
product.tplwhile the core now expectsproduct.twig. The override simply never loads. - Directory relocation: Twig templates live under a different subfolder structure within the theme, so your Smarty path points to a directory the core no longer scans.
- Syntax differences: Twig uses
{{ variable }}and{% if %}tags where Smarty used{$variable}and{if}, so even if the file loads, it can throw fatal errors. - Hook registration: Some template assignments that Smarty handled through
{hook h='displayX'}now pass through Twig functions, which alters how your module receives data.
The blind spot is that PrestaShop often maintains backward compatibility layers. A module can still hook correctly and output HTML through its own Smarty template, masking the fact that your theme override of a core product page template is no longer executing. The page looks normal because the module works, but your customisations are absent.
When you carry Smarty overrides forward, audit every overridden template during pre-upgrade testing on a staging environment. Check the template directory structure in your version's documentation and compare the expected file extensions against what your theme contains. A quick inventory of .tpl versus .twig files inside the theme's module folders will reveal which overrides are still live and which became dead weight.
How to Diagnose Which Override Is Broken (Step-by-Step)
When template overrides break silently after a core update, the first challenge is finding which file is at fault. Production stores often look normal because Smarty caches old compiled templates, while the error only surfaces on a fresh page load or in a specific browser session. Working through this checklist in order will narrow the problem down quickly.
Step 1: Enable Developer Mode
Developer mode disables template caching and displays PHP errors directly on the page. In newer PrestaShop versions, open /config/defines.inc.php and set _PS_MODE_DEV_ to true. In PrestaShop 1.7, enable it from the back office under Advanced Parameters, Performance.
Once enabled, reload the affected page. A broken override typically throws a clear error naming the missing template file or the incorrect function call. This stops Smarty from serving the cached, working version of the template.
Step 2: Check the PHP and Smarty Logs
If the page renders without errors in developer mode, inspect the server logs. PrestaShop writes PHP errors to the var/logs directory in modern versions, while the web server access and error logs live in your hosting control panel. Look for entries mentioning Smarty template or the specific theme folder name around the timestamp of the failed request.
Smarty errors often state "unable to load template" followed by the expected file path. That path tells you whether PrestaShop is looking for a file in your theme's override directory or in the core location.
Step 3: Compare Override File Paths with Current Core Templates
A core update sometimes renames or moves template files, which silently orphans your override. Open the override directory at /themes/YOUR_THEME/modules/ and list every overridden module folder. Then compare those names against the actual modules present in /modules/ after the update.
- Note the exact module folder names you have overridden.
- Check whether those modules still exist in the core after the update.
- Verify that the template filenames inside your override match the current files inside the module's own views/templates folder.
- Pay special attention to files that moved from .tpl to .twig extensions during a major version upgrade.
If a filename no longer matches, the core update probably renamed or restructured that template. Your override still exists, but PrestaShop never loads it because the hook or display call now references a different file.
Step 4: Test Overrides One at a Time
When multiple overrides exist, isolate each one. Temporarily rename all override files in a single module folder, then reload the page. If the error disappears, one of those files is the culprit. Restore them one by one, reloading after each restoration, until the broken file reveals itself.
This binary search approach is far faster than inspecting every file manually.
Step 5: Verify the Override Is Actually Being Called
A subtle failure occurs when the override loads without error but the expected output never appears. To confirm PrestaShop is using your file at all, add a temporary HTML comment at the top of the override template, such as: Then view the page source in your browser. If the comment is absent, the override is not being executed no matter how correct the code looks.
The problem then lies in the hook registration or the module's display call, not in the template syntax itself. Check whether the module still registers the same hooks after the core update, since hook names occasionally change between major versions.
Once you identify the broken override, the fix usually follows the same pattern. FME Modules documents how their PrestaShop modules handle template overrides, which is a useful reference when restoring compatibility after an upgrade. Compare the failing file against the updated core template, merge your customisations into the new structure, and clear the cache to confirm the repair.
Can Updating Only the Theme Solve the Problem?
In most cases, updating only the theme will not solve the problem. Most template overrides broken after a core update are not caused by the theme itself, but by changes in how PrestaShop core now handles template files, either .tpl or .twig paths.
When you update the core, PrestaShop may change the location where it looks for template files or alter the variables passed to those templates. Your theme's overrides were written against the old structure, so they no longer match what the core expects. Updating the theme only refreshes the theme's own files; it does nothing to reconcile that mismatch.
There are two scenarios where a theme update genuinely helps:
- Your theme developer released a compatibility patch specifically built for the new PrestaShop version you installed. Check the theme's changelog before assuming this.
- The overrides live inside the theme's own folder structure, and the theme update replaces them with versions adapted to the new core templates.
If neither applies, expect to do manual work. You typically need to compare your overrides against the new core templates and merge changes by hand. PrestaShop's built-in override tooling can also regenerate some files, but it cannot automatically fix logic that relies on changed variables or removed template blocks.
Before touching any file, confirm you know where your overrides actually live. Overrides placed in /themes/YOUR_THEME/modules/ behave differently from overrides in /overrides/ or child theme folders. A theme update may erase theme-level overrides entirely, which is a separate cause of silent breakage worth checking first.
The pragmatic approach: update the theme only if the developer states compatibility with your PrestaShop version. Otherwise, plan for a manual override audit against the updated core templates.
Best Practices to Prevent Overrides from Breaking on Future Updates
The silent breakage problem feels inevitable only when you approach overrides as a one-time task. A few disciplined habits reduce the chance that a core update will quietly kill your templates. None require exotic tooling, but they do require changing how you structure override files in the first place.
Stop Copying Whole Core Templates
The most common mistake is duplicating an entire .tpl or .twig file into your theme just to change one line. When PrestaShop alters that file in a core update, your copy no longer matches the new structure. The override still loads, but it references variables or blocks that no longer exist, which is exactly how you end up with template overrides broken on production without any error on staging.
- Copy only the specific block or portion you need to modify, not the whole file.
- Wrap your changes in conditional checks where possible, so missing variables degrade gracefully.
- Document which core version your override was built against, ideally in a comment at the top of the file.
Use Hooks Instead of Template Overrides Wherever Possible
PrestaShop exposes dozens of display hooks that let you inject content without touching a single template file. If your goal is to add a banner, a widget, or a custom snippet, a hook-based module is almost always more resilient than a template override. Core updates rarely remove hooks without deprecation warnings, whereas template files change frequently between minor versions.
For structural changes that hooks cannot achieve, keep the override as small as possible. A 10-line override that targets one variable will survive an update far better than a 400-line copy of a core template.
Configure theme.yml Correctly
PrestaShop themes declare their parent and dependency information in the theme.yml file. When this file is incomplete or points to the wrong parent, the theme can fall back to unexpected template sources after an update. Verify that your theme.yml references the correct parent theme and that all template paths resolve to the intended directory.
This matters most after a major PrestaShop version change, because the default theme structure itself shifts between releases. A theme.yml that worked on one version may not map correctly to a newer version, leaving your overrides pointing at directories that no longer exist.
Test Every Update on a Staging Environment First
Staging servers exist for exactly this reason. Before you run a core update on production, replicate the update on a staging copy that mirrors your live theme, modules, and database. Run a visual regression pass over every page that uses an override, and check the logs for template-related notices. This catches the majority of silent breakage before customers ever see it.
Pay particular attention to pages you rarely view, such as order confirmation, email templates, and invoice generation. These templates break most often and go unnoticed the longest because they only render under specific conditions.
Adopt a Change Log for Every Override
Keep a simple record of each override you create: which core file it replaces, what version of PrestaShop it was built against, and what change you made. When the next core update arrives, you can compare the new core template against your override quickly instead of reverse-engineering the diff from memory.
The most reliable way to avoid broken overrides is to treat them as code you maintain, not files you install and forget. Overrides demand the same discipline as custom modules: version control, documentation, and periodic review against the current core.
What Should You Do If Your Override Is Beyond Repair?
When an override has drifted too far from the current core template, patching it line by line becomes a losing battle. The realistic move is a full rebuild, but not a blind copy of the old code. Rebuild against the updated core file as your reference, then reapply only the customisations your store actually needs.
Before you start rewriting, ask whether an override is even the right mechanism. PrestaShop hooks often achieve the same result without touching core templates at all. If your customisation adds a block, changes a display element, or alters behaviour on a specific page, explore hook-based modules first. They survive core updates far better because they attach to stable hook points rather than duplicating template structure.
The cleanest long-term strategy is to keep template overrides small, documented, and isolated to genuine layout changes only. If you find yourself copying hundreds of lines from a core file, you have likely crossed the line into maintenance debt that will break again on the next PrestaShop release.
When a rebuild is unavoidable, structure it for maintainability:
- Diff the old override against the current core file to catalogue every change you made originally.
- Strip out any code that duplicated core logic unnecessarily, keeping only the genuine customisation.
- Add clear comments in the template explaining why each override exists and which PrestaShop version it targets.
- Test the rebuilt override on a staging copy of your store with caching disabled before touching production.
If the customisation belongs to a specific feature rather than a global layout change, check whether an existing PrestaShop module already provides it. Many common overrides, such as product list tweaks or checkout display changes, have well-maintained module equivalents that receive their own updates. Offloading the maintenance burden to a module keeps your theme cleaner and reduces the chances of template overrides being broken by the next major upgrade.
Finally, treat the rebuild as an opportunity to reduce future risk. PrestaShop's migration toward Twig templates will continue, so any Smarty override you rebuild today may face the same problem in a later version. Prioritise the customisations that deliver real commercial value, and consider dropping anything that no longer earns its maintenance cost.