Study guide · Caching, Logging and Debugging

Fast, traceable, error-free: Caching, logging and debugging in TYPO3

As of November 15, 2026 · TYPO3 14.3 LTS · about 22 min read

A good TYPO3 site is fast, and when something goes wrong, you find the cause in minutes. The cache, the log and error handling make this possible. Our example is the extension my_extension with a conference list and a nightly import.

The page cache

A cache stores computed results so they are not produced again every time. This lowers response time and server load. It never replaces the database as the permanent source. The real difficulty is invalidation: outdated entries must disappear in time, through tags or a lifetime.

The most important cache is called pages. It stores the fully rendered output of a page, by default in the database table cache_pages. Uncached parts such as a USER_INT are only placeholders there and are rendered again on every request. The page cache separates languages and user groups by itself. Caching of Extbase plugins is covered in the course “Extbase: MVC, Plugins und Views”.

Request for page 12 In the page cache? Yes No Cache hit Deliver stored HTML, re-render only USER_INT parts Cache miss Render the page and store it with tag pageId_12 Editor saves a record on page 12 All entries tagged pageId_12 are flushed
Hit, rebuild and flushing via the page tag.

Flushing on save: Every cached page carries the tag pageId_ followed by its UID. When an editor changes a text on page 12, the DataHandler flushes exactly this tag. Other pages stay cached.

Flushing other pages too: The home page shows teasers of our conferences from folder 20. When someone saves a conference there, the home page stays outdated. The page TSconfig TCEMAIN.clearCacheCmd on the folder fixes this. It lists pages that are flushed as well, several separated by commas.

TCEMAIN.clearCacheCmd = 1
Page TSconfig for folder 20. clearCacheCmd is one, so every save also flushes the home page.

Lifetime: Globally, config.cache_period applies, in seconds. For a single page you choose the cache lifetime in the page properties, for example 15 minutes. The value of the page takes precedence. TYPO3 already respects start and stop times of the content on the page. For records from another folder you name the table and the folder in TypoScript. Then the cache expires exactly when the next conference becomes visible.

config.cache.1 = tx_myextension_domain_model_conference:20
For page 1, the start and stop times of the conferences in folder 20 count as well. With the key all, this would apply to all pages.

If a page shows old content after editing, usually a matching tag or a clearCacheCmd is missing. Or an upstream proxy or the browser still delivers the old copy.

The Caching Framework

Besides pages, TYPO3 has many named caches. Each one consists of a frontend, which defines how data is passed in, and a backend, which defines where it is stored. An entry has an identifier, data, a lifetime and any number of tags.

  • The VariableFrontend serializes any PHP value. It is the default.
  • The PhpFrontend stores PHP code that TYPO3 includes with require. It needs a backend that can store PHP code, such as FileBackend or SimpleFileBackend.

The Core ships these backends: Typo3DatabaseBackend as the default, FileBackend, SimpleFileBackend, RedisBackend, MemcachedBackend, ApcuBackend, TransientMemoryBackend and NullBackend. The TransientMemoryBackend keeps values only for the current request. The NullBackend stores nothing. The SimpleFileBackend does not support tags.

In Composer installations, file caches live in var/cache, those with PHP code in var/cache/code, all others in var/cache/data. The folder var is deliberately outside the web root. In an emergency you may delete its cache contents.

Every cache belongs to groups. The group pages holds the frontend caches such as pages and rootline. The group system holds caches that are expensive to rebuild, such as core and fluid_template. lowlevel holds caches you should never flush by hand, and all stands for all the others. A custom cache in the group pages is flushed together with the page cache.

Flushing: On the command line, cache:flush flushes all caches. The command belongs in every deployment. With the option group you flush only one group, such as pages, system or di. New in TYPO3 14 is cache:flushtags for flushing by tag. cache:warmup, in contrast, builds caches up.

vendor/bin/typo3 cache:flush
vendor/bin/typo3 cache:flush --group pages
vendor/bin/typo3 cache:flushtags tx_myextension_conference_5
Three commands. Flush everything, flush only the group pages, and since TYPO3 14, flush all entries with one tag.

composer clear-cache only flushes the download cache of Composer. There is no command cache:clear like in Symfony, and no URL parameter for flushing either.

In the backend, the lightning icon in the toolbar flushes the frontend caches or all caches. Editors without admin rights only see the entry for the frontend caches with the user TSconfig options.clearCache.pages. In the same way, options.clearCache.all controls flushing all caches. The Maintenance module has the card “Flush TYPO3 and PHP Cache”. It also flushes the PHP opcode cache.

A custom cache for my_extension

The import stores conferences in a custom cache myextension_conferences. You register it in ext_localconf.php. Without further settings it uses the VariableFrontend and the database. The assignment operator with a double question mark lets administrators override the settings.

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myextension_conferences'] ??= [];
In ext_localconf.php, myextension_conferences gets an empty array under cacheConfigurations, only if no entry exists yet.

You get the cache through dependency injection. In Services.yaml you define a service that the CacheManager creates with getCache(). Do not use the CacheManager itself in ext_localconf.php. The Core provides the runtime cache the same way, as cache.runtime.

services:
  cache.myextension_conferences:
    class: TYPO3\CMS\Core\Cache\Frontend\FrontendInterface
    factory: ['@TYPO3\CMS\Core\Cache\CacheManager', 'getCache']
    arguments: ['myextension_conferences']
The service cache.myextension_conferences is created by the factory CacheManager getCache with the name of the cache.

The method get() returns false if no valid entry exists, not null. You check for that, compute the value and store it with set(). A check with has() is unnecessary and can hit an entry that has just expired.

$id = 'list_' . $languageId . '_' . hash('xxh3', implode(',', $groupIds));
$value = $this->cache->get($id);
if ($value === false) {
    $value = $this->buildList();
    $this->cache->set($id, $value, ['tx_myextension_conference'], 86400);
}
The identifier consists of a prefix, the language and a hash of the user groups. If get returns false, the list is computed and stored with set, with a tag and a lifetime of one day.
  • Allowed characters: An identifier contains only letters, digits, underscore, percent, minus and ampersand, with at most 250 characters. Question marks or spaces from a search query lead to an InvalidArgumentException. That is why you use a prefix plus a hash of the input.
  • Full context: A custom cache knows neither the language nor the user groups. If the identifier is just teaser_list, everyone gets the list built first, even in the wrong language or with members-only entries.
  • Tags and lifetime: The third parameter sets tags, the fourth the lifetime in seconds. Without it, the default of the backend applies. With flushByTag() you delete all entries of a tag. Reading only works through the identifier.

If you need a value several times during one request only, use the cache runtime. It uses the TransientMemoryBackend.

Tagging pages: When the import changes conference 5, its detail page should be rebuilt. To do this, the controller gives the page a tag. In the frontend, the request attribute frontend.cache.collector collects all tags of the page. The former TSFE no longer exists in TYPO3 14.

$request->getAttribute('frontend.cache.collector')
    ->addCacheTags(new CacheTag('tx_myextension_conference_5'));
The cache collector comes from the request, and addCacheTags receives a CacheTag for conference 5.

After the import, flushCachesInGroupByTags() flushes the entries with these tags in all caches of the group pages. flushCachesByTag() does this in all caches. flushCaches() would flush everything and is needlessly expensive. remove(), in contrast, expects the identifier of a single entry, not a tag.

Logging with PSR-3

TYPO3 logs according to the PSR-3 standard. The easiest way is to have a LoggerInterface injected through the constructor. The logger is then named after your class. Alternatively the class implements LoggerAwareInterface with the LoggerAwareTrait, and the container calls setLogger(). Creating loggers or writers yourself is not intended.

public function __construct(private readonly LoggerInterface $logger) {}

try {
    $this->importFile($file);
} catch (ImportFailedException $e) {
    $this->logger->error('Import of {file} failed', ['file' => $file, 'exception' => $e]);
}
The importer receives a logger in its constructor. In the catch block it writes a message of level error with the placeholder file and passes the file and the exception in the context.

Because the code only knows the interface, you can swap the implementation without changing the class. In a test you pass a NullLogger, which discards everything. PSR-3 does not define where messages are written.

Placeholders in curly braces keep the text the same. The values go into the context array, and the writers fill them in when writing. That way you can search and group similar entries. Concatenated strings or sprintf are harder to analyse. An exception belongs in the context under the key exception. There is no method exception().

PSR-3 knows eight levels from RFC 5424. Each has its own method, plus log() with level, message and context.

Eight levels in PSR-3 from most severe (top) to least severe (bottom) emergency System is unusable alert Act immediately critical Critical condition error An action failed warning Problem, but it goes on Default: warning and up to var/log notice Normal but significant info Information about the flow debug Details for development By default, levels below the line are discarded.
Without its own configuration, TYPO3 writes from warning upwards.

If the import skips a broken record and continues, warning fits. If the database is gone and the site is down, that is alert, because someone must act immediately. emergency means the system is unusable. Levels such as fatal or trace do not exist in PSR-3.

Where the messages go

Without its own configuration, the FileWriter writes all entries from warning upwards to a file typo3_ plus hash in the folder var/log. In classic installations this is typo3temp/var/log. So messages from debug() are discarded until you enable them.

Writers decide the target. FileWriter and RotatingFileWriter write to files. The DatabaseWriter writes to the table sys_log, visible in the module Administration, Log. The SyslogWriter writes to the syslog of the operating system, the PhpErrorLogWriter to the PHP error log. Since TYPO3 14.2 the option logTable of the DatabaseWriter is deprecated. For a custom table you derive a writer from AbstractWriter.

Configuration lives in the LOG section of TYPO3_CONF_VARS, by namespace and level. This line applies to all classes under MyVendor\MyExtension from info upwards:

$GLOBALS['TYPO3_CONF_VARS']['LOG']['MyVendor']['MyExtension']['writerConfiguration'][LogLevel::INFO][FileWriter::class] = ['logFileInfix' => 'myextension'];
For the namespace MyVendor MyExtension, a FileWriter with the infix myextension is registered from level INFO upwards.
  • The entries end up in a file such as typo3_myextension_ plus hash.
  • A level applies to itself and all more severe levels. A writer under ERROR therefore takes no warning.
  • The LogManager searches from general to specific for the most specific configuration. It replaces the global one, and the two do not apply together.

Channels: If classes from different namespaces should write together to a file security.log, you put their loggers into a channel security with the attribute Channel. TYPO3 then looks up the configuration under this name.

Processors enrich entries. The IntrospectionProcessor adds file, line, class and function of the caller. Others add memory usage or request data. They live under processorConfiguration.

An entry is a LogRecord made of requestId, creation time, component, level, message and data.

Showing or hiding errors

On the live server the application context Production applies. On errors, visitors only see a short message, no paths or SQL queries. In the context Development, details with file and line appear. In public that would be a security risk. Development does not switch off the cache.

Which handler displays an exception is decided by displayErrors under SYS:

displayErrors 1 0 -1 IP matches devIPmask? Yes No Debug DebugExceptionHandler Message and full stack trace Production ProductionExceptionHandler Short message, details only in the log Both handlers log. The default value is -1.
displayErrors and devIPmask choose the exception handler.

The setting exceptionalErrors defines which PHP errors become exceptions. You register a custom productionExceptionHandler in config/system/additional.php. In ext_localconf.php it would be too late, because TYPO3 sets up the handlers before that.

The fastest way to switch is in the module System, Settings under “Configuration Presets”. The preset Debug sets displayErrors to 1 and devIPmask to an asterisk, switches on the debug options for frontend and backend and enables the deprecation log. The preset Live switches all of this off. Public systems always run with Live.

Errors in a plugin: In the production context, a separate handler replaces only the affected content element with “Oops, an error occurred!” and an identifier. In TYPO3 14 this is the request ID. With it you find the entry in the log. With config.contentObjectExceptionHandler set to 0 you see the exception with stack trace instead. On live systems the handler stays active. At most you switch it off for administrators with a condition.

Error pages: In the site configuration you choose a handler per HTTP code under errorHandling. Page shows a TYPO3 page from errorContentSource, which editors maintain as usual. Fluid renders the file from errorFluidTemplate. PHP calls a class from errorPhpClassFQCN, which returns its own response through PageErrorHandlerInterface and handlePageError(). A page named 404 or an ErrorDocument in the htaccess file has no effect.

errorHandling:
  - errorCode: 404
    errorHandler: Page
    errorContentSource: 't3://page?uid=42'
  - errorCode: 503
    errorHandler: Fluid
    errorFluidTemplate: 'EXT:site/Resources/Private/Templates/Error503.fluid.html'
For 404, the handler Page shows page 42. For 503, the handler Fluid renders a file from the site package.

If a controller must output the 403 page immediately, it creates the response with accessDeniedAction() of the ErrorController and throws it as a PropagateResponseException. The middleware ResponsePropagation catches it.

Finding errors

Where to look? First in the TYPO3 logs in var/log. A white page is usually caused by a fatal error before TYPO3 can output anything. Then the PHP error log and the error.log of Apache or nginx in /var/log help. Where PHP writes is set by error_log in the php.ini. If the database is reachable, the module Administration, Log shows the table sys_log. The table sys_history only contains changes to records.

Reading a stack trace: At the top is the place where the exception was thrown, below it the callers. The first line from your own code is often the best starting point. You can search for the TYPO3 exception code directly.

Looking at values:

  • In a Fluid template, the ViewHelper f:debug shows a variable with type and properties, and with inline set to 1 right in place. There is no ViewHelper f:dump.
  • DebuggerUtility::var_dump() from Extbase shows objects including lazy proxies. The depth is limited to 8, and maxDepth plus lists of class and property names to hide make the output smaller. On the command line, plainText gives text instead of HTML, and ansiColors adds colour. With return you get a string.
  • The global function debug() only outputs something if the IP matches devIPmask.
  • In PHP, var_dump() also shows types and lengths. print_r() with true as the second parameter returns a string. An echo on an array only prints the word Array. Exit or die end the script immediately.

Debug output does not appear again from cached pages. It does not belong on live systems.

php -l Classes/Service/ConferenceImporter.php
xdebug.mode=debug
xdebug.start_with_request=trigger
php minus l only checks a file for syntax errors. Below it, the Xdebug settings: mode debug, start only with a trigger.

The lint command php -l only reports syntax errors and does not run the code. That is why it does not find a missing class. You switch on Xdebug 3 with the mode debug. With the start value trigger, a session only begins when the request carries XDEBUG_TRIGGER as a cookie or parameter. The IDE listens on port 9003, port 9000 was for Xdebug 2. At a breakpoint you inspect variables and the call stack and continue step by step. Xdebug slows things down and does not belong on live systems.

Your own exceptions: Throw your own classes such as ImportFailedException, which extend RuntimeException. Then callers can catch them specifically. The code is usually a Unix timestamp. The class Error is meant for errors of the PHP engine. Exception and Error both implement Throwable, but Error does not extend Exception. So a catch for Exception does not catch a TypeError. Only catch where you can react sensibly, never with an empty catch block.

try {
    $this->readRows($handle);
} catch (\JsonException $e) {
    throw new ImportFailedException('File not readable', 1763197200, $e);
} finally {
    fclose($handle);
}
The catch block throws its own exception and passes the old one as previous. The finally block always closes the file, even after an error.

With the old exception as previous, getPrevious() later returns the cause. The finally block always runs, which is why fclose belongs there.

  1. Make the error reproducible with minimal steps.
  2. Put log output or breakpoints at the decisive places.
  3. If it used to work, git bisect finds the change to blame.
  4. Afterwards, keep the case as a test.

Investigating slow pages

TYPO3 itself gives you a first value: if debug in the FE section is set to true, it sends the header X-TYPO3-Parsetime with the rendering time.

The Admin Panel shows more. It is a bar at the bottom of the frontend from the system extension adminpanel. It has nothing to do with the backend module Administration. It only appears under three conditions:

  • You are logged in to the backend in the same browser. A frontend login is not enough.
  • In user TSconfig at least one module is enabled, for example with admPanel.enable.all. Administrators have this by default.
  • In TypoScript, config.admPanel is set to 1.

The application context does not matter. The Info module shows the cache status and the number of USER_INT objects. The TypoScript module shows run times. The Debug module shows PSR-14 events, log entries and all SQL queries. In the preview, the panel also shows hidden content.

You register custom modules in ext_localconf.php, in the EXTCONF section under adminpanel and modules, with the class under module and optionally before or after. The module implements ModuleInterface, usually through AbstractModule. The ShortInfoProviderInterface provides a short info for the bar, the ResourceProviderInterface its own CSS and JavaScript. The ModuleSettingsProviderInterface offers settings that the user sets in the panel. The RequestEnricherInterface enriches the request before rendering, and the DataProviderInterface collects data for display.

Key points

  • Saving flushes the tag of the page, and TCEMAIN.clearCacheCmd flushes further pages.
  • You register custom caches in ext_localconf.php and get them through dependency injection. get() returns false if nothing is there.
  • An identifier contains only simple characters and everything the result depends on.
  • cache:flush flushes everything, and since TYPO3 14 cache:flushtags flushes by tag.
  • Logger through injection, placeholders in the text, values and exception in the context.
  • By default, entries from warning upwards go to var/log. The most specific writer configuration replaces the general one.
  • displayErrors and devIPmask choose the exception handler. On live systems the preset Live applies.
  • The Admin Panel needs a backend login, user TSconfig and config.admPanel.

Terms

Cache tag
A label that lets you delete many cache entries at once.
Cache group
Caches that are flushed together, such as pages or system.
devIPmask
IP addresses that may see developer output.
N+1 problem
One query for the list and another one for each entry.
Processor
Adds data to a log entry before it is written.
Writer
Decides where a log entry is written.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Explained 14.3, chapters Caching, Logging, Error and exception handling, Debugging
  • TypoScript Reference 14.3, config (cache_period, cache, contentObjectExceptionHandler, admPanel)
  • Documentation of the system extension adminpanel 14.3
  • PSR-3 Logger Interface (php-fig.org), Xdebug 3 documentation
  • Source code TYPO3 14.3 (typo3/cms-core, cms-frontend, cms-adminpanel, cms-install), checked for the default log configuration, cache groups, identifier rules, presets and the error message in the frontend

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications