Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Troubleshooting¶

The following sections contain hints to help you solve common problems. Note that you should also check the section "ADMIN TOOLS > Environment > Environment Status" in the Install Tool or TYPO3 backend. TYPO3 will inform you about errors and warnings in your installation. Follow the advice given there to fix those issues. This helps to solve or prevent most issues.

Lost passwords¶

Resetting lost admin passwords¶

If the admin password got lost you can create a new admin user from the admin tools section Maintenance.

Directly from the TYPO3 backend the admin tools can only be accessed by admin users with system maintainer rights. And such a user is lacking.

However the admin tools can be accessed as Install tool by calling:

https://examle.com/typo3/install.php

The install tool expects the install tool password. If you have also lost this one see Resetting lost install tool passwords.

Once in the admin tool go to Maintenance > Create Administrative User and click on Create Administrator. In the following dialogue you can enter a new username and password for the new administrator.

Use this new administrator to log into the TYPO3 backend. In the module Backend Users you can change the passwords of existing users, including admins.

Resetting lost install tool passwords¶

As long as you have writing access to the file typo3conf/LocalConfiguration.php you can reset the install tool password.

Just enter any desired password into the dialogue asking for your install tool password. If it is not correct you will get a message like this one:

"Given password does not match the install tool login password. Calculated hash:
$argon2i$v=xyz"

Copy this hash including the $argon2i part and any trailing dots. Then open the file typo3conf/LocalConfiguration.php and replace the following array entry:

'BE' => [
   'installToolPassword' => '$argon2i$v=xyz',
],

Note

If the new install tool password does not work, check if it gets overridden later in the LocalConfiguration.php or in the AdditionalConfiguration.php if one exists. If you can still not log into the install tool check if there are errors in the logs when debugging is turned on.

Debug settings¶

During troubleshooting, in the "Settings > Configuration Presets" section of the Install Tool, under "Debug settings", you should select the "Debug" preset. This is especially helpful, if e.g. in the Frontend you only see a blank page. With debug settings activated, the PHP error message will be displayed, which will help you narrow down the problem.

You may also have to enable this TypoScript setting:

config.contentObjectExceptionHandler = 0

Apache¶

Some settings may require adjustment for TYPO3 to operate correctly.

Enable mod_rewrite¶

TYPO3 makes use of several Apache modules (see System Requirements for more information).

If mod_rewrite is not enabled, the URL handling will not work properly (specifically the mapping of the URLs TYPO3 uses internally to "speaking URLs") and you might get 404 (page not found) errors.

Tip

How Apache modules are enabled, depends on your system. Look in the documentation for your operating system distribution.

For example, the modules can be enabled by editing your http.conf file, locating the required modules and removing the preceding hash symbol:

#LoadModule expires_module modules/mod_expires.so
#LoadModule rewrite_module modules/mod_rewrite.so

Or, just do

a2enmod rewrite expires

As usual, after changing configuration, you must reload / restart the Apache service.

Adjust ThreadStackSize on Windows¶

If you are running TYPO3 on top of Windows, the extension manager might not appear. Instead you might only see a blank screen in the right frame.

This problem is caused by the value of ThreadStackSize, which on Windows systems by default is set too low. To fix this, add the following lines at the end of your httpd.conf file:

<IfModule mpm_winnt_module>
  ThreadStackSize 8388608
</IfModule>

PHP¶

Install Tool¶

The "System Environment" section of the Install Tool provides detailed information about any missing PHP modules and any other settings that may not be configured correctly.

For example, the PHP extensions openssl and fileinfo must be enabled. This can be achieved by adding (or uncommenting) the following lines in the [PHP] section of your php.ini file:

extension=fileinfo.so
extension=openssl.so

On a Windows-based server, these are the extension files:

extension=php_fileinfo.dll
extension=php_openssl.dll

PHP Caches, Extension Classes etc.¶

There are some situations which can cause what appear to be totally illogical problems after an upgrade:

If extensions override classes in which functions have changed. Solution: Try disabling all extensions and then enable them one by one until the error recurs.
If a PHP cache somehow fails to re-cache scripts: in particular, if a change happened to a parent class overridden by a child class which was not updated. Solution: Remove ALL cached PHP files (for PHP-Accelerator, remove /tmp/phpa_*) and restart Apache.

Opcode cache messages¶

No PHP opcode cache loaded¶

You do not have an opcode cache system installed or activated. If you want better performance for your website, then you should use one. The best choice is OPcache for PHP 5.5 onwards.

This opcode cache is marked as malfunctioning by the TYPO3 CMS Team.¶

This will be shown if an opcode cache system is found and activated, which is known to have "too many" errors and won't be supported by TYPO3 CMS (no bugfixes, security fixes or anything else). In current TYPO3 versions only OPcache is supported

This opcode cache may work correctly but has medium performance.¶

This will be shown if an opcode cache system is found and activated, which has some nitpicks. For example we cannot clear the cache for one file (which we changed) but only can reset the complete cache itself. This will happen with:

OPcache before 7.0.2 (Shouldn't be out in the wild.)
APC before 3.1.1 and some mysterious configuration combinations.
XCache
ZendOptimizerPlus

This opcode cache should work correctly and has good performance.¶

Well it seems that all is ok and working. Maybe you can tweak something more but this is out of our knowledge of your user scenario.

MySQL¶

Character Set¶

TYPO3 uses UTF-8 encoding, you will need to ensure that your instance of MySQL also uses UTF-8. When installing TYPO3 for the first time, you can select UTF-8 encoding when you create the database for the first time. For an existing database, you will have to set each table and column to use UTF-8.

TYPO3¶

Cached Files in typo3temp/¶

Generally you should know that TYPO3 generates temporary "cached" files and PHP scripts in <var-path>/cache/ (usually either typo3temp/var/cache or var/cache). You can remove the whole <var-path>/cache directory at any time; the directory structure and all the caches will be re-written on the next hit to the system.

A shortcut to remove these caches can be found in the Install Tool, under "Important Actions". This might be useful in the event your cache files become damaged and your system is not running correctly. The Install Tool won't load any of these caches or any extension, so it should be safe to use regardless of the corrupt state of the Caches.

Amongst other caches, under <var-path>/cache/code/core/ you find files like these:

-rw-rw----   1 www-data   www-data   61555  2014-03-26 16:28   ext_localconf_8b0519db6112697cceedb50296df89b0ce04ff70.php
-rw-rw----   1 www-data   www-data   81995  2014-03-26 16:28   ext_tables_c3638687920118a92ab652cbf23a9ca69d4a6469.php

These files simply contain all ext_tables.php and ext_localconf.php files of the installed extensions concatenated in the order they are loaded. Therefore including one of these files would be the same as including potentially hundreds of PHP files and should improve performance.

Concerning these files you have to consider the following:

Making changes to these files does not make sense, because they can be removed and recreated from the "originals" at any time. You should instead change the "originals".
If you make changes to the original ext_tables.php or ext_localconf.php files in your extensions, you will have to clear the cached files away for your changes to take effect.

Possible Problems With the Cached Files¶

Changing the absolute path to TYPO3¶

If you change the path of the TYPO3 installation, you might get a lot of errors like "Failed opening ..." or "Unable to access ...". The problem is that absolute file paths are hard-coded inside the cached files.

Fix: Clean the cache using the Install Tool: Go to "Important Actions" and use the "Clear all caches" function. Then hit the page again.

Changing Image Processing Settings¶

When you change the settings for Image Processing (in normal mode), you must take into account that old images may still be in the typo3temp/ folder and that they prevent new files from being generated! This is especially important to know, if you are trying to set up image processing for the very first time.

The problem is solved by clearing the files in the typo3temp/ folder. Also make sure to clear the database table "cache_pages".