TYPO3 Fehlerbehebung: Die 20 häufigsten Fehler und ihre Lösung

Eine TYPO3 Fehlerbehebung beginnt mit drei Fragen: In welchem Kontext läuft die Website, was steht im Log, und was hat sich zuletzt geändert? Wenn Sie diese drei Fragen zuerst klären, lassen sich die meisten der 20 Fehler unten auf eine einzige Ursache eingrenzen. Zu jedem Fehler finden Sie die Meldung, die üblichen Ursachen und die Lösung. Alles gilt für TYPO3 v13 und v14, im Composer-Modus und in klassischen Installationen. Der Leitfaden stammt von NITSAN Technologies, dem Unternehmen hinter T3Planet und Gold-Mitglied der TYPO3 Association. Er sammelt die Fehler, die uns in TYPO3-Projekten und im Support am häufigsten begegnen.

Bei der TYPO3 Fehlerbehebung suchen Sie zuerst den echten Fehler hinter einem Symptom, bevor Sie irgendetwas ändern. TYPO3 verbirgt technische Details absichtlich vor Besuchern, deshalb ist die Meldung auf dem Bildschirm selten die Ursache. Die Ursache steht fast immer in einem Log, und meist hängt sie mit der letzten Änderung zusammen.

1. In welchem Kontext läuft die Website? Im Kontext Production zeigt TYPO3 statt des Fehlers nur eine kurze Meldung. Im Kontext Development werden Fehler in Inhaltselementen nicht mehr abgefangen, und mit den Debug-Einstellungen unten sehen Sie die vollständige Exception. Den Kontext legt die Umgebungsvariable TYPO3_CONTEXT fest.
2. Was steht im Log? TYPO3 schreibt Warnungen und Fehler in eine Logdatei. Dort finden Sie die genaue Fehlermeldung und den numerischen Exception-Code.
3. Was hat sich zuletzt geändert? Ein Update von Core oder Extension, eine neue Extension, ein Deployment, ein PHP-Upgrade oder ein Serverumzug. Prüfen Sie genau diese Änderung zuerst, oder machen Sie sie rückgängig.

Die Backend-Pfade in diesem Leitfaden verwenden die Modulnamen von TYPO3 v13. In TYPO3 v14 heißt Web jetzt Content, File heißt Media, Site Management heißt Sites, Admin Tools heißt System, und die bisherige Gruppe System (Log, Scheduler, Backend Users) heißt Administration. Alle Pfade nennen die englischen Modulnamen; in einem deutschsprachigen Backend sind die Bezeichnungen übersetzt.

Keine Einträge im Log? Standardmäßig schreibt TYPO3 in jedem Kontext alles ab WARNING in die Logdatei. Bleibt die Datei leer, prüfen Sie, ob der Benutzer des Webservers in var/log/ schreiben darf (klassisch: typo3temp/var/log/) und ob eine eigene writerConfiguration in config/system/additional.php den Standard-Filewriter ersetzt hat.

Auf einer Entwicklungs- oder Staging-Kopie lassen Sie TYPO3 den vollständigen Fehler anzeigen:

• Der schnelle Weg: Admin Tools > Settings > Configuration Presets > Debug settings > Debug. Wenn Sie fertig sind, stellen Sie wieder auf Live um.
• Der wiederholbare Weg: Legen Sie den Kontext pro Umgebung fest, zum Beispiel in der Konfiguration des Webservers:

Ändern Sie danach nur die Einstellungen, die Sie wirklich brauchen, in config/system/additional.php (klassisch: typo3conf/system/additional.php). Ändern Sie einzelne Schlüssel, nie ein ganzes Array wie ['SYS']: Wer es ersetzt, entfernt das Trusted-Hosts-Muster, den Encryption Key und jede andere Systemeinstellung.

Schalten Sie displayErrors = 1 nie auf einer Live-Website ein. In der Produktion behalten Sie die Voreinstellung und lesen das Log. Alternativ setzen Sie displayErrors = -1 und tragen Ihre eigene IP-Adresse in devIPmask ein, dann sehen nur Sie die Fehler.

1. „Oops, an error occurred!“

Diese Meldung samt Code erscheint, wenn ein einzelnes Inhaltselement im Kontext Production nicht gerendert werden kann. Der Rest der Seite funktioniert weiter, denn der Exception-Handler für Content-Objekte fängt den Fehler für dieses eine Element ab.

• Ursache finden: Suchen Sie in der Logdatei nach dem Code aus der Meldung. Die passende Zeile nennt die Exception, ihren numerischen Code und die Datei. Den numerischen Code schlagen Sie in der Exceptions-Referenz nach.
• Häufige Ursachen: ein Fluid-Template oder Partial, das nicht gefunden wird, eine fehlende Extension hinter einem Plugin, ein fehlerhafter TypoScript-Pfad, ein Datenbankfeld, das ein Update entfernt hat.
• Nur auf einer Entwicklungskopie zeigen Sie den vollständigen Fehler direkt in der Seite an:

Möchten Sie stattdessen den Text für Besucher ändern, genügt eine Zeile, zum Beispiel config.contentObjectExceptionHandler.errorMessage = Dieser Teil der Seite konnte nicht geladen werden. Code: %s.

2. 500 Internal Server Error

Der Webserver konnte die Anfrage nicht abschließen. Oft kam TYPO3 gar nicht mehr dazu, etwas zu protokollieren, also beginnen Sie beim Fehlerlog von Webserver und PHP.

• Fataler PHP-Fehler: Eine Extension oder die PHP-Version passt nicht zu TYPO3. Das PHP-Fehlerlog nennt Datei und Zeile.
• Rewrite-Regeln: Unter Apache muss mod_rewrite aktiv sein, und public/.htaccess muss die Datei sein, die TYPO3 mitliefert. In einem Unterverzeichnis setzen Sie RewriteBase auf diesen Pfad. Unter nginx müssen alle Anfragen, die keine Datei treffen, an index.php gehen.
• Limits: Speicherlimit oder maximale Ausführungszeit erreicht. Siehe Fehler 10 unten.

3. „No TypoScript record found!“

Das Frontend findet für diese Website kein TypoScript. Aktuelle TYPO3-Versionen zeigen „No TypoScript record found!“, ältere meldeten „No TypoScript template found“.

• Öffnen Sie Site Management > TypoScript, wählen Sie die Root-Seite der Website und legen Sie einen TypoScript-Datensatz an, markiert als Root der Website.
• Nutzt die Website ein Site Set (TYPO3 v13), kommt das TypoScript stattdessen aus dem Set. Prüfen Sie, ob die Site-Konfiguration das Set noch als Abhängigkeit aufführt.
• Nach einem Import oder dem Verschieben von Seiten prüfen Sie, ob der Datensatz auf der Root-Seite genau dieser Website liegt.

4. Syntaxfehler in TypoScript

Eine falsche Klammer, ein fehlendes Ende einer Bedingung oder ein vertippter Pfad lässt Teile der Seite verschwinden, ganz ohne Fehlermeldung.

• Active TypoScript (Site Management > TypoScript) zeigt die endgültigen Konstanten und das Setup als Baum. So sehen Sie, ob Ihr Wert angekommen ist.
• Included TypoScript listet alle Includes in ihrer Reihenfolge und zeigt für jeden die Warnungen des Syntax-Scanners mit Zeilennummern.
• Die Syntax selbst behandeln unsere TypoScript-Tipps und das Cheatsheet zu Bedingungen.

5. Weiße Seite ohne Meldung

Eine komplett weiße Seite bedeutet meist einen fatalen PHP-Fehler bei ausgeschalteter Fehleranzeige. TYPO3 konnte nicht einmal mehr seine eigene Fehlerseite ausgeben.

• Lesen Sie zuerst das PHP-Fehlerlog; dort steht die Ursache.
• Typische Ursachen: eine Extension, die Ihre PHP-Version nicht unterstützt, das Speicherlimit, ein Syntaxfehler in config/system/additional.php.
• Haben Sie keinen Zugriff auf die Server-Logs, schalten Sie in einer Kopie der Website das Preset Debug ein und stellen Sie den Fehler dort nach.

6. Die 404-Seite funktioniert nicht

Seit TYPO3 v9 legen Sie Fehlerseiten pro Website in der Site-Konfiguration fest, nicht mehr in einer globalen Einstellung.

1. Site Management > Sites > Ihre Website bearbeiten > Reiter Error Handling.
2. Fügen Sie einen Handler mit dem Fehlercode 404 und dem Typ Show content from page hinzu und wählen Sie Ihre 404-Seite aus.
3. Speichern Sie, leeren Sie die Caches und testen Sie mit einer URL, die es nicht gibt.

Typische Anzeichen einer fehlerhaften Einrichtung: Die 404-Seite antwortet mit Status 200, erscheint in der falschen Sprache oder endet in einer Weiterleitungsschleife. Prüfen Sie den Statuscode in den Entwicklertools des Browsers. Stellen Sie dann sicher, dass die 404-Seite ohne Anmeldung sichtbar ist, zur selben Website gehört und in jede Sprache der Website übersetzt ist. Mehr zur Konfigurationsdatei selbst: TYPO3 Site-Konfiguration.

7. JavaScript-Fehler und blockierte Skripte

Slider, Formulare oder Menüs funktionieren nicht mehr, und die Browser-Konsole zeigt rote Fehler.

• Skriptfehler: eine doppelt geladene Bibliothek, eine nach dem Deployment fehlende Datei, eine durch config.concatenateJs oder einen Minifier veränderte Skript-Reihenfolge. Schalten Sie auf einer Testkopie das Zusammenfassen ab, um die Datei zu finden.
• Blockiert durch die Content Security Policy: Ist eine Content Security Policy aktiv, verweigert der Browser Inline-Skripte und Skripte von Drittanbietern, die die Policy nicht erlaubt, und meldet das in der Konsole. In TYPO3 v13 ist die Policy fürs Frontend optional und wird über die Feature-Flags security.frontend.enforceContentSecurityPolicy und security.frontend.reportContentSecurityPolicy oder eine csp.yaml pro Website aktiviert. Erlauben Sie die Quelle in der Policy, statt die Policy abzuschalten.

8. Die Backend-Anmeldung lädt nicht oder springt zurück

• „The current host header value does not match the configured trusted hosts pattern“: Die Domain fehlt in ['SYS']['trustedHostsPattern']. Ergänzen Sie sie in config/system/settings.php oder additional.php. Das passiert oft nach einem Domainwechsel oder hinter einem neuen Proxy.
• Das Anmeldeformular lädt ohne Fehler neu: Das Session-Cookie wird nicht gesetzt. Prüfen Sie, ob Sie das Backend über dasselbe Protokoll und dieselbe Domain aufrufen, für die es konfiguriert ist (['BE']['lockSSL'], ['BE']['cookieDomain']), und löschen Sie dann die Cookies der Website im Browser.
• Leere Anmeldeseite oder 500-Fehler: ein fataler PHP-Fehler. Lesen Sie das PHP-Fehlerlog; wurde gerade eine Extension installiert, hilft Fehler 11 weiter.

9. „The Install Tool is locked“

Das eigenständige Install Tool unter /typo3/install.php öffnet sich nur, wenn eine Kennzeichnungsdatei existiert. Legen Sie eine leere Datei namens ENABLE_INSTALL_TOOL in var/transient/ oder config/ (Composer) beziehungsweise in typo3conf/ (klassisch) an, laden Sie die Seite neu und löschen Sie die Datei wieder, wenn Sie fertig sind.

Können Sie sich noch als System Maintainer im Backend anmelden, nutzen Sie dort die Module Maintenance, Settings, Upgrade und Environment; sie brauchen keine Kennzeichnungsdatei. Warum die Sperre wichtig ist, erklärt unsere Checkliste zur TYPO3 Sicherheit.

10. „Allowed memory size of ... bytes exhausted“

PHP hat abgebrochen, weil eine Anfrage mehr Speicher brauchte als erlaubt. Typische Auslöser sind die Bildverarbeitung sehr großer Uploads und lange Listen im Backend.

• Limit in PHP erhöhen: TYPO3 v13 und v14 haben keine eigene Speichereinstellung. Die TYPO3-Systemanforderungen empfehlen mindestens 256 MB.

• Starten Sie danach PHP-FPM oder den Webserver neu und leeren Sie die Caches: Admin Tools > Maintenance > Flush TYPO3 and PHP Cache.
• Kehrt der Fehler zurück, suchen Sie die Extension oder den Task, der den Speicher braucht, statt das Limit noch einmal anzuheben.

Viele Fehler in diesem Leitfaden beginnen auf dem Server: PHP-Versionen, Limits, Rechte, Mail. Website Builder betreibt TYPO3 für Sie auf einem Server, der genau dafür eingerichtet ist, mit automatischen TYPO3-Updates und täglichen Backups.

Website Builder für TYPO3 entdecken

11. Fatal Error direkt nach Installation oder Update einer Extension

Die Extension unterstützt Ihre TYPO3- oder PHP-Version nicht, oder sie hat etwas geändert, auf das Ihr Projekt angewiesen ist. Entfernen Sie sie zuerst und untersuchen Sie den Fehler danach.

• Composer-Installationen: Führen Sie composer remove vendor/package aus oder verlangen Sie eine Version, die Ihre TYPO3- und PHP-Version unterstützt, danach composer install und vendor/bin/typo3 extension:setup.
• Klassische Installationen: Führen Sie typo3/sysext/core/bin/typo3 extension:deactivate <extension_key> aus. Scheitert auch die CLI, entfernen Sie den Eintrag der Extension aus typo3conf/PackageStates.php.
• Leeren Sie die Caches mit vendor/bin/typo3 cache:flush oder löschen Sie var/cache/ (klassisch: typo3temp/var/cache/).

12. Fehler nach einem TYPO3-Upgrade

Nach einem Major-Upgrade stammen Fehler meist aus einem übersprungenen Schritt, nicht aus dem Core selbst. Gehen Sie diese Liste der Reihe nach durch:

1. Upgrade-Wizards ausführen: Admin Tools > Upgrade > Upgrade Wizard oder vendor/bin/typo3 upgrade:run.
2. Datenbank abgleichen: Admin Tools > Maintenance > Analyze Database Structure, und übernehmen Sie die Änderungen.
3. Eigenen Code prüfen: Admin Tools > Upgrade > Scan Extension Files listet den Code in Ihren Extensions, der entfernte oder geänderte Core-APIs nutzt.
4. PHP prüfen: Die PHP-Version muss zu den Anforderungen des TYPO3-Releases passen, auf dem Webserver und auf der Kommandozeile. TYPO3-Version und Composer-Modus prüfen zeigt, wo Sie nachsehen.
5. Modul Reports prüfen: System > Reports > Status Report listet Konfigurationsprobleme, die TYPO3 selbst erkennt.

Sie planen den nächsten Versionssprung? TYPO3 Update oder Upgrade erklärt, welcher Weg passt, TYPO3 Rector automatisiert einen großen Teil der Code-Migration, und der Leitfaden zu TYPO3 v14 behandelt das aktuelle Release.

13. „Class ... not found“

Die Informationen zum Laden der Klassen sind veraltet, meist nach einem Deployment oder einer manuellen Dateiänderung.

• Composer-Installationen: Führen Sie composer dump-autoload aus (oder composer install auf dem Server) und leeren Sie danach die Caches.
• Klassische Installationen: Admin Tools > Maintenance > Rebuild PHP Autoload Information.
• Gehört die Klasse zu einer Extension, die nicht mehr installiert ist, installieren Sie sie wieder oder entfernen Sie das TypoScript oder die Konfiguration, die noch darauf verweist.

14. Das Deprecation-Log füllt die Festplatte

Das Protokollieren von Deprecations ist standardmäßig aus. Eingeschaltet wird es durch das Preset Debug oder eine eigene Logging-Konfiguration, und nach einem Upgrade kann es Tausende Zeilen pro Minute schreiben.

• Stellen Sie das Preset zurück: Admin Tools > Settings > Configuration Presets > Debug settings > Live.
• Oder schalten Sie den Deprecation-Writer ausdrücklich ab, in config/system/additional.php:

Lesen Sie die Deprecations, bevor Sie sie abschalten: Jede steht für Code, der mit der nächsten Major-Version nicht mehr funktioniert.

15. Keine Verbindung zur Datenbank

Meldungen wie SQLSTATE[HY000] [2002] Connection refused oder Access denied for user bedeuten, dass TYPO3 die Datenbank nicht erreicht.

• Prüfen Sie Host, Port, Datenbankname, Benutzer und Passwort in config/system/settings.php unter ['DB']['Connections']['Default'] oder in den Umgebungsvariablen, aus denen Ihr Setup sie liest.
• localhost nutzt einen Socket, 127.0.0.1 nutzt TCP; scheitert das eine, versuchen Sie das andere. In Docker ist der Host der Name des Datenbank-Services, nicht localhost.
• Nach einem Serverumzug prüfen Sie, ob der Datenbankserver Verbindungen vom neuen Host zulässt.
• Sobald die Verbindung steht, führen Sie Admin Tools > Maintenance > Analyze Database Structure aus.

16. E-Mails werden nicht versendet

Formular-Mails, Passwort-Resets oder Benachrichtigungen kommen nie an.

• transport_smtp_encrypt ist ein Schalter mit true oder false: true bedeutet SMTPS, meist auf Port 465. Auf Port 587 lassen Sie ihn auf false, STARTTLS wird dann automatisch verwendet.
• Senden Sie eine Testmail über Admin Tools > Environment > Test Mail Setup. Die angezeigte Fehlermeldung nennt das Problem: falsche Zugangsdaten, ein gesperrter Port oder eine Absenderadresse, die der Mailserver ablehnt.
• Viele Hoster sperren ausgehenden Port 25; nutzen Sie stattdessen den SMTP-Server Ihres Anbieters.

17. Bilder werden nicht verarbeitet

Vorschaubilder fehlen, Bilder behalten ihre Originalgröße, oder das Backend meldet „image processing is disabled“.

• Prüfen Sie, ob das Programm auf dem Server installiert ist (gm version oder convert -version) und ob der Pfad auf dessen Verzeichnis zeigt.
• Admin Tools > Environment > Image Processing rendert Testbilder, so sehen Sie, welche Operation fehlschlägt.

18. Fehlende Schreibrechte und fehlende Dateien

• „Directory ... not writable“ oder leere Log- und Cache-Ordner: Der Benutzer des Webservers muss in var/, public/typo3temp/ und public/fileadmin/ schreiben dürfen (klassisch: typo3temp/, fileadmin/, typo3conf/). Admin Tools > Environment > Directory Status zeigt, welcher Ordner das Problem ist.

Ersetzen Sie www-data durch den Benutzer, unter dem Ihr Webserver läuft. In Docker muss der Benutzer im Container Eigentümer der eingebundenen Ordner sein.

• Im Backend als fehlend markierte Dateien: Eine Datei wurde außerhalb von TYPO3 umbenannt, verschoben oder gelöscht, zum Beispiel per FTP, und der Dateiindex passt nicht mehr zur Festplatte. Verschieben und benennen Sie Dateien im Modul Filelist um, holen Sie verlorene Dateien aus einem Backup zurück und führen Sie den Scheduler-Task File Abstraction Layer: Update storage index aus.

19. Die Website läuft nur nach dem Leeren des Caches

Seiten zeigen alte Inhalte, Änderungen erscheinen nicht, oder Fehler verschwinden nach dem Leeren des Caches und kommen wieder.

• Leeren Sie alles: Admin Tools > Maintenance > Flush TYPO3 and PHP Cache oder vendor/bin/typo3 cache:flush.
• Lädt das Backend nicht, löschen Sie var/cache/ (klassisch: typo3temp/var/cache/).
• Setzen Sie nach einem Deployment den OPcache durch einen Neustart von PHP-FPM zurück, sonst führt PHP weiter den alten Code aus.
• Passiert es immer wieder, suchen Sie nach einer Extension, die so in den Cache schreibt, dass es nicht zu ihren Tags passt.

Alle Wege zum Leeren des Caches, vom Backend bis zur Kommandozeile, finden Sie in TYPO3-Cache leeren.

20. Scheduler-Tasks und CLI-Befehle schlagen fehl

Tasks laufen nicht, zeigen „never executed“, oder die Kommandozeile meldet Fehler, die das Backend nicht zeigt.

• Der Cronjob: Der Scheduler läuft nur, wenn ein Cronjob ihn aufruft, zum Beispiel alle 15 Minuten:

In klassischen Installationen lautet der Befehl typo3/sysext/core/bin/typo3 scheduler:run.

• Zwei PHP-Versionen: Die Kommandozeile nutzt oft ein anderes PHP-Binary als der Webserver. Führen Sie php -v als Benutzer des Cronjobs aus und rufen Sie das richtige Binary mit vollem Pfad auf.
• Ein hängender Task: System > Scheduler zeigt Tasks, die als laufend markiert sind; stoppen Sie ihn dort, bevor er erneut startet.

Mehr zur Einrichtung: Cronjobs mit dem TYPO3 Scheduler.

Der TYPO3 Core deckt den größten Teil der Fehlerbehandlung ab. Für eine tiefergehende TYPO3 Fehlerbehebung ergänzen diese Werkzeuge ihn. Jede hier genannte Extension eines Drittanbieters unterstützte laut extensions.typo3.org oder Packagist TYPO3 v12 oder neuer, als das TYPO3-Team von NITSAN diesen Leitfaden im Oktober 2026 geprüft hat.

Speziell für Fluid-Templates behandelt unser Leitfaden zu TYPO3 Fluid das Debuggen mit <f:debug>.

Die meisten der oben genannten Fehler lassen sich mit vier Gewohnheiten vermeiden:

1. Drei Umgebungen: lokale Entwicklung, eine Staging-Kopie, die der Produktion entspricht, und die Produktion selbst. Testen Sie Updates und neue Extensions zuerst auf Staging.
2. Ein Kontext pro Umgebung: Development lokal, Production (oder ein Unterkontext wie Production/Staging) auf Staging und live, gesetzt durch den Webserver oder den Container.
3. Logs, die Sie tatsächlich lesen: Behalten Sie den Standard-Filewriter, rotieren Sie die Logdateien und lassen Sie sich von einem Monitoring wie mklog oder Zabbix warnen, bevor es ein Besucher tut.
4. Updates in fester Reihenfolge: sichern, mit Composer aktualisieren, Upgrade-Wizards ausführen, Datenbank abgleichen, Caches leeren, testen. Danach bringen Sie genau diesen Stand in die Produktion.

T3Planet wird von NITSAN entwickelt, Gold-Mitglied der TYPO3 Association, mit zertifizierten TYPO3-Integratoren und -Entwicklern. Kehrt ein Fehler immer wieder zurück, oder möchten Sie ihn nicht selbst suchen? Dann analysiert und behebt das Team von NITSAN ihn gemeinsam mit Ihnen. Mit einem Supportvertrag halten wir Ihre Installation zudem auf dem aktuellen Stand.

TYPO3 Support und Wartung ansehen