> For the complete documentation index, see [llms.txt](https://xoops.gitbook.io/xoops-install-upgrade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xoops.gitbook.io/xoops-install-upgrade/upgrading/upgrade/ustep-03.md).

# Troubleshooting

## Smarty 4 Template Errors

The most common class of problems when upgrading from XOOPS 2.5.x to 2.7.0 is Smarty 4 template incompatibility. If you skipped or did not complete the [Preflight Check](/xoops-install-upgrade/upgrading/upgrade/preflight.md), you may see template errors on the front end or in the admin area after the upgrade.

To recover:

1. **Re-run the preflight scanner** at `/upgrade/preflight.php`. Apply any automatic repairs it offers, or fix flagged templates manually.
2. **Clear the compiled template cache.** Remove everything except `index.html` from `xoops_data/caches/smarty_compile/`. Smarty 3 compiled templates are not compatible with Smarty 4 and stale files can cause confusing errors.
3. **Switch to a shipped theme temporarily.** From the admin area, select `xbootstrap5` or `default` as the active theme. This will confirm whether the problem is limited to a custom theme or is site-wide.
4. **Validate any custom themes and module templates** before switching production traffic back on. Pay particular attention to templates that use `{php}` blocks, deprecated modifiers, or non-standard delimiter syntax — these are the most common Smarty 4 breakages.

See also the Smarty 4 section in [Special Topics](/xoops-install-upgrade/installation/specialtopics.md).

## Permission Issues

The XOOPS Upgrade may need to write to files that have previously been made read-only. If this is the case, you will see a message like this:

![XOOPS Upgrade Make Writable Error](/files/-L_EkQV3ZAJPNOmADdT8)

The solution is to change the permissions. You can change permissions using FTP if you do not have more direct access. Here is an example using FileZilla:

![FileZilla Change Permission](/files/-L_EkQV5p2nsv2drDMDK)

## Debugging Output

You can enable extra debugging output in the logger by adding a debug parameter to the URL used to launch the Upgrade:

```
http://example.com/upgrade/?debug=1
```