TYPO3 Troubleshooting: 20 Common Errors and How to Fix Them

TYPO3 troubleshooting starts with three questions: which context is the site running in, what does the log say, and what changed last? Answer those first, and most of the 20 errors below narrow down to a single cause. Each one is listed with the message you see, the usual causes and the fix, for TYPO3 v13 and v14 in Composer and classic installations. The guide comes from NITSAN Technologies, the TYPO3 Association Gold Member behind T3Planet. It collects the errors we meet most often in projects and support work.

TYPO3 troubleshooting means finding the real error behind a symptom before you change anything. TYPO3 hides technical details from visitors on purpose, so the message on screen is rarely the cause. The cause is almost always in a log, and it is usually tied to the last change.

1. Which context is the site running in? In Production, TYPO3 shows a short message instead of the error. In Development, content element errors are no longer hidden, and with the debug settings below TYPO3 shows the full exception. The context comes from the TYPO3_CONTEXT environment variable.
2. What does the log say? TYPO3 writes warnings and errors to a log file. The exact error message and its numeric exception code are there.
3. What changed last? A core or extension update, a new extension, a deployment, a PHP upgrade or a server move. Undo or check that change first.

Backend paths in this guide use the TYPO3 v13 module names. In TYPO3 v14, Web is called Content, File is called Media, Site Management is called Sites, Admin Tools is called System, and the former System group (Log, Scheduler, Backend Users) is called Administration.

No entries in the log? By default TYPO3 writes WARNING and higher to the log file in every context. If the file stays empty, check that the web server user can write to var/log/ (classic: typo3temp/var/log/), and that no custom writerConfiguration in config/system/additional.php has replaced the default file writer.

On a development or staging copy, let TYPO3 show the full error:

• The quick way: Admin Tools > Settings > Configuration Presets > Debug settings > Debug. Switch back to Live when you are done.
• The repeatable way: set the context per environment, for example in the web server configuration:

Then change only the settings you need in config/system/additional.php (classic: typo3conf/system/additional.php). Change single keys, never a whole array such as ['SYS']: replacing it removes the trusted hosts pattern, the encryption key and every other system setting.

Never enable displayErrors = 1 on a live site. On production, keep the default and read the log, or use displayErrors = -1 with your own IP address in devIPmask to see errors only from your connection.

1. "Oops, an error occurred!"

TYPO3 shows this message, followed by a code, when one content element fails to render and the context is Production. The rest of the page still works, because the content object exception handler catches the error for that one element.

• Find the cause: search the log file for the code shown in the message. The matching line names the exception, its numeric code and the file. Look the numeric code up in the Exceptions reference.
• Common causes: a Fluid template or partial that cannot be found, a missing extension behind a plugin, a broken TypoScript path, a database field an update removed.
• On a development copy only, show the full error inside the page:

To change the visitor message instead, set one line, for example config.contentObjectExceptionHandler.errorMessage = Sorry, this part of the page could not be loaded. Code: %s.

2. 500 Internal Server Error

The web server could not finish the request. TYPO3 often never got the chance to log anything, so start with the web server and PHP error log.

• Fatal PHP error: an extension or the PHP version does not match TYPO3. The PHP error log names the file and line.
• Rewrite rules: on Apache, mod_rewrite must be active and public/.htaccess must be the one TYPO3 ships. In a subdirectory, set RewriteBase to that path. On nginx, all requests that are not files must go to index.php.
• Limits: memory limit or execution time reached. See error 10 below.

3. "No TypoScript record found!"

The frontend finds no TypoScript for this site. Current TYPO3 versions show "No TypoScript record found!"; older versions said "No TypoScript template found".

• Open Site Management > TypoScript, select the root page of the site and create a TypoScript record, marked as the root of the site.
• If the site uses a site set (TYPO3 v13), the TypoScript comes from the set instead. Check that the site configuration still lists the set as a dependency.
• After an import or page move, check that the record sits on the root page of this site.

4. TypoScript syntax errors

A wrong brace, a missing condition end or a mistyped path makes parts of the page disappear without any error message.

• Active TypoScript (Site Management > TypoScript) shows the final constants and setup as a tree, so you can see whether your value arrived.
• Included TypoScript lists every include in order and shows the syntax scanner warnings for each one, with line numbers.
• The TypoScript tips and the conditions cheatsheet cover the syntax itself.

5. White page, no message

A completely white page usually means a fatal PHP error while error display is off. TYPO3 could not even show its own error page.

• Read the PHP error log first; it names the cause.
• Typical causes: an extension that does not support your PHP version, the memory limit, a syntax error in config/system/additional.php.
• If you cannot read the server logs, switch the Debug preset on in a copy of the site and reproduce the error there.

6. The 404 page does not work

Since TYPO3 v9, error pages are set per site in the site configuration, not in a global setting.

1. Site Management > Sites > edit your site > tab Error Handling.
2. Add a handler with error code 404, type Show content from page, and select your 404 page.
3. Save, flush the caches and test with a URL that does not exist.

Symptoms of a broken setup: the 404 page answers with status 200, shows the wrong language, or ends in a redirect loop. Check the status code in the browser's developer tools. Then check that the 404 page is visible without login, belongs to the same site and is translated into every site language. More on the configuration file itself: TYPO3 site configuration.

7. JavaScript errors and blocked scripts

Sliders, forms or menus stop working, and the browser console shows red errors.

• Script errors: a library loaded twice, a missing file after a deployment, a script order changed by config.concatenateJs or a minifier. Switch concatenation off on a test copy to find the file.
• Blocked by Content Security Policy: with a Content Security Policy active, the browser refuses inline and third-party scripts that the policy does not allow, and the console says so. In TYPO3 v13 the frontend policy is opt-in, through the feature flags security.frontend.enforceContentSecurityPolicy and security.frontend.reportContentSecurityPolicy or a csp.yaml per site. Allow the source in the policy instead of switching the policy off.

8. The backend login page does not load or loops

• "The current host header value does not match the configured trusted hosts pattern": the domain is not in ['SYS']['trustedHostsPattern']. Add it in config/system/settings.php or additional.php. This often appears after a domain change or behind a new proxy.
• The login form reloads without an error: the session cookie is not set. Check that the backend is opened over the same protocol and domain it is configured for (['BE']['lockSSL'], ['BE']['cookieDomain']), then clear the browser cookies for the site.
• A blank login page or a 500 error: a fatal PHP error. Read the PHP error log, then see error 11 if an extension was just installed.

9. "The Install Tool is locked"

The standalone Install Tool at /typo3/install.php only opens when a flag file exists. Create an empty file named ENABLE_INSTALL_TOOL in var/transient/ or config/ (Composer) or in typo3conf/ (classic), reload the page, and delete the file when you are done.

If you can still log in to the backend as a system maintainer, use the Maintenance, Settings, Upgrade and Environment modules there instead; they need no flag file. Why the lock matters is part of our TYPO3 Security checklist.

10. "Allowed memory size of ... bytes exhausted"

PHP stopped because a request needed more memory than allowed. Image processing of very large uploads and long lists in the backend are typical triggers.

• Raise the limit in PHP: TYPO3 v13 and v14 have no memory setting of their own. The TYPO3 system requirements recommend at least 256 MB.

• Restart PHP-FPM or the web server afterwards, then flush the caches: Admin Tools > Maintenance > Flush TYPO3 and PHP Cache.
• If the error returns, find the extension or task that needs the memory instead of raising the limit again.

Many errors in this guide start on the server: PHP versions, limits, permissions, mail. Website Builder hosts TYPO3 for you on a server set up for it, with automatic TYPO3 updates and daily backups.

Explore Website Builder for TYPO3

11. Fatal error right after installing or updating an extension

The extension does not support your TYPO3 or PHP version, or it changed something your project relies on. Remove it first, then investigate.

• Composer installations: run composer remove vendor/package, or require a version that supports your TYPO3 and PHP version, then composer install and vendor/bin/typo3 extension:setup.
• Classic installations: run typo3/sysext/core/bin/typo3 extension:deactivate <extension_key>. If the CLI fails as well, remove the extension's entry from typo3conf/PackageStates.php.
• Flush the caches with vendor/bin/typo3 cache:flush, or delete var/cache/ (classic: typo3temp/var/cache/).

12. Errors after a TYPO3 upgrade

After a major upgrade, errors usually come from a step that was skipped, not from the core itself. Work through this list in order:

1. Run the upgrade wizards: Admin Tools > Upgrade > Upgrade Wizard, or vendor/bin/typo3 upgrade:run.
2. Compare the database: Admin Tools > Maintenance > Analyze Database Structure, and apply the changes.
3. Check your own code: Admin Tools > Upgrade > Scan Extension Files lists the code in your extensions that uses removed or changed core APIs.
4. Check PHP: the PHP version must match what the TYPO3 release requires, on the web server and on the command line. How to check the TYPO3 version and Composer mode shows where to look.
5. Check the Reports module: System > Reports > Status Report lists configuration problems TYPO3 detects itself.

Planning the next version jump? TYPO3 update vs upgrade explains which path fits, TYPO3 Rector automates much of the code migration, and the TYPO3 v14 guide covers the current release.

13. "Class ... not found"

The class loading information is out of date, usually after a deployment or a manual file change.

• Composer installations: run composer dump-autoload (or composer install on the server), then flush the caches.
• Classic installations: Admin Tools > Maintenance > Rebuild PHP Autoload Information.
• If the class belongs to an extension that is no longer installed, reinstall it or remove the TypoScript or configuration that still points to it.

14. The deprecation log fills the disk

Deprecation logging is off by default. It is switched on by the Debug preset or by custom logging configuration, and after an upgrade it can write thousands of lines a minute.

• Switch the preset back: Admin Tools > Settings > Configuration Presets > Debug settings > Live.
• Or switch the deprecation writer off explicitly, in config/system/additional.php:

Read the deprecations before you switch them off: each one is code that will break in the next major version.

15. Database connection failed

Errors such as SQLSTATE[HY000] [2002] Connection refused or Access denied for user mean TYPO3 cannot reach the database.

• Check host, port, database name, user and password in config/system/settings.php under ['DB']['Connections']['Default'], or in the environment variables your setup reads them from.
• localhost uses a socket and 127.0.0.1 uses TCP; if one fails, try the other. In Docker, the host is the name of the database service, not localhost.
• After a server move, check that the database server allows connections from the new host.
• Once the connection works, run Admin Tools > Maintenance > Analyze Database Structure.

16. Emails are not sent

Form mails, password resets or notifications never arrive.

• transport_smtp_encrypt is a true or false switch: true means SMTPS, usually on port 465. On port 587 leave it false, and STARTTLS is used automatically.
• Send a test from Admin Tools > Environment > Test Mail Setup. The error it shows names the problem: wrong credentials, a blocked port, or a sender address the mail server refuses.
• Many hosts block outgoing port 25; use the provider's SMTP server instead.

17. Images are not processed

Thumbnails are missing, images keep their original size, or the backend shows "image processing is disabled".

• Check that the program is installed on the server (gm version or convert -version) and that the path points to its folder.
• Admin Tools > Environment > Image Processing renders test images, so you can see which operation fails.

18. Permission errors and missing files

• "Directory ... not writable" or empty log and cache folders: the web server user must be able to write to var/, public/typo3temp/ and public/fileadmin/ (classic: typo3temp/, fileadmin/, typo3conf/). Admin Tools > Environment > Directory Status shows which folder fails.

Replace www-data with the user your web server runs as. In Docker, the user inside the container must own the mounted folders.

• Files marked as missing in the backend: a file was renamed, moved or deleted outside TYPO3, for example over FTP, so the file index no longer matches the disk. Move and rename files in the Filelist module, restore lost files from a backup, and run the scheduler task File Abstraction Layer: Update storage index.

19. The site only works after the cache is cleared

Pages show old content, changes do not appear, or errors disappear after a cache flush and come back.

• Flush everything: Admin Tools > Maintenance > Flush TYPO3 and PHP Cache, or vendor/bin/typo3 cache:flush.
• If the backend does not load, delete var/cache/ (classic: typo3temp/var/cache/).
• After a deployment, reset OPcache by restarting PHP-FPM, otherwise PHP keeps running the old code.
• If it keeps happening, look for an extension that writes into the cache in a way that does not match its tags.

Every way to clear the cache, from the backend to the command line, is in how to clear the TYPO3 cache.

20. Scheduler tasks and CLI commands fail

Tasks do not run, show "never executed", or the command line reports errors the backend does not show.

• The cron job: the scheduler only runs when a cron job calls it, for example every 15 minutes:

In classic installations the command is typo3/sysext/core/bin/typo3 scheduler:run.

• Two PHP versions: the command line often uses a different PHP binary than the web server. Run php -v as the cron user and call the right binary with its full path.
• A task that hangs: System > Scheduler shows tasks marked as running; stop it there before it runs again.

More on setting this up: cron jobs with the TYPO3 Scheduler.

The TYPO3 core covers most error handling. For deeper TYPO3 troubleshooting, these tools add to it. Each third-party extension listed supported TYPO3 v12 or later on extensions.typo3.org or Packagist when NITSAN's TYPO3 team checked this guide in October 2026.

For Fluid templates in particular, the TYPO3 Fluid guide covers debugging with <f:debug>.

Most of the errors above are preventable with four habits:

1. Three environments: local development, a staging copy that matches production, and production. Test updates and new extensions on staging first.
2. One context per environment: Development locally, Production (or a sub-context such as Production/Staging) on staging and live, set by the web server or container.
3. Logs you actually read: keep the default file writer, rotate the log files, and use a monitor such as mklog or Zabbix to alert you instead of a visitor.
4. Updates in a fixed order: back up, update with Composer, run the upgrade wizards, compare the database, flush the caches, test. Then deploy the same state to production.

T3Planet is built by NITSAN, a TYPO3 Association Gold Member with certified TYPO3 integrators and developers. If an error keeps returning, or you would rather not chase it yourself, NITSAN's team analyses and fixes it with you. Under a support agreement, we also keep your installation current.

See TYPO3 support and maintenance