Problems and Errors
Føhn reports what goes wrong in the commands you already run: wp foehn inspect, wp foehn discovery:status and the error a failed render throws. Each message says what is wrong and, when the cause is known, gives the fix on one line, after Fix:.
Classes discovery skips
A class that carries an attribute but breaks the contract of that attribute is not registered. Discovery skips it, records why, and registers every other class. One broken class does not stop the site.
| Attribute | What makes discovery skip the class |
|---|---|
#[AsPostType] | The class does not extend Timber\Post |
#[AsTaxonomy] | The class does not extend Timber\Term |
#[AsTimberModel] | The class extends neither Timber\Post nor Timber\Term |
#[AsBlock], #[AsContextProvider], #[AsTemplateController] | The class does not implement the interface of the attribute |
#[AsBlockBinding] | The class does not implement the interface, or the source name has no namespace |
#[AsSettingsPage] | The class does not implement the interface, or it declares no form |
#[AsCliCommand], #[AsSeeder] | The class does not implement the interface of the attribute |
#[AsTwigExtension] | The class does not extend Twig\Extension\AbstractExtension |
#[AsCron] | The class has no public __invoke() method, or the cron expression is not valid |
#[AsJob] | __invoke() is missing, or it does not take one parameter typed with a class |
#[AsRewriteRule] | after is not top or bottom |
#[AsPostMeta] | The type, the object type, the REST schema or the sanitizer is not valid (only that key is skipped) |
#[AsAcfBlock], #[AsAcfFieldGroup] | The class does not implement the interface of the attribute |
hooks in foehn.config.php | The class does not exist |
The records are discovery items, so the discovery cache stores them with the rest: a request served from the cache knows what the scan skipped. When debug is on in the configuration, each one is also raised as a PHP warning on every request.
Reading the problems
wp foehn inspect starts its summary with them:
problems — 2: App\Models\Gallery #[AsPostType], App\Models\Article #[AsPostType]
post-types — 1: article
...
Problems with their fix: wp foehn inspect problemswp foehn inspect problems prints each one in full, and --format=json gives class, attribute, reason and fix for each row:
wp foehn inspect problems --format=json{
"problems": [
{
"class": "App\\Models\\Gallery",
"attribute": "#[AsPostType]",
"reason": "App\\Models\\Gallery has #[AsPostType] but does not extend Timber\\Post, so the post type is not registered.",
"fix": "Declare App\\Models\\Gallery with `extends \\Timber\\Post`."
}
]
}fix is null when the cause is not known: a class named in hooks whose discovery threw gives the message of the exception only.
The problems section of inspect also lists the links between post types and taxonomies that point at nothing: a post type that names a taxonomy in taxonomies, or a taxonomy that names a post type in postTypes, when no Føhn attribute declares it and WordPress does not register it. WordPress ignores such a link without a word. Core types such as category and the types of plugins count as registered. These rows are computed when inspect runs, so they are not in discovery:status.
wp foehn discovery:status prints the classes discovery skipped, one line each:
Problems: 1
App\Models\Gallery has #[AsPostType] but does not extend Timber\Post, so the post type is not registered. Fix: Declare App\Models\Gallery with `extends \Timber\Post`.After a fix, run wp foehn discovery:clear when the discovery cache is on, so the next request scans the class again.
Rendering errors
TimberViewEngine throws Studiometa\Foehn\Views\ViewRenderingFailed, a RuntimeException, when a view cannot be rendered. Its message names the view that was asked for, which is often not the template that failed.
A Twig error keeps the template and the line where Twig failed, and Twig's own message. The Twig error is the previous exception:
Rendering the view 'pages/single' failed in partials/card.twig at line 2: Unable to find template "partials/missing.twig" (looked into: /var/www/html/wp-content/themes/my-theme/templates).A missing view names every view that was tried, the directories Timber searched, and the file to create:
No template found for the views 'pages/single-product', 'pages/single'. Searched pages/single-product.twig, pages/single.twig in: /var/www/html/wp-content/themes/my-theme, /var/www/html/wp-content/themes/my-theme/templates. Fix: create one of pages/single-product.twig, pages/single.twig in /var/www/html/wp-content/themes/my-theme/templates.The directories are the ones Timber's loader searches, from TimberConfig::$templatesDir and the timber/locations filter. exists() asks the same loader, so a view exists() finds is a view render() finds.
The error log
In the local and development environments, Føhn writes the errors of the site to a log, and wp foehn errors prints the last one. An agent that changed code reads it after it loads a page, instead of a browser or the PHP log. For the JavaScript errors of the page, see Browser errors.
wp foehn errorsStudiometa\Foehn\Views\ViewRenderingFailed: Rendering the view 'pages/404' failed in pages/404.twig at line 18: Variable "price" does not exist.
exception at 2026-11-12 11:25:42 UTC in vendor/studiometa/foehn/src/Views/ViewRenderingFailed.php:67
twig pages/404.twig:18
caused by Twig\Error\RuntimeError: Variable "price" does not exist in "pages/404.twig" at line 18.
GET /no-such-page/ · template 404 · controller App\Controllers\Error404Controller · view pages/404.twig
context site, theme, user, menus, post, posts, current_year
theme/app/Controllers/Error404Controller.php:21 Studiometa\Foehn\Views\TimberViewEngine->render()
+7 other framesWhat is recorded
- each uncaught exception;
- each fatal error;
- each warning and notice raised in the theme's own code: a PHP file of the theme directory, or a Twig template of the theme. The
vendorandnode_modulesdirectories of the theme are not its own code. A warning of WordPress, a plugin or a Composer package is not recorded.
A warning that error_reporting() leaves out is not recorded: a warning silenced with @, and a notice when WP_DEBUG is off, because WordPress then leaves notices out. Deprecations are not recorded: wp foehn verify --profile=updates reports them. One request writes each error once, and at most 20 entries.
Recording starts when the theme boots Føhn. An error raised before, in WordPress core or in a plugin that loads first, is not recorded. An exception that code catches is not recorded.
The fields of an entry
| Field | Content |
|---|---|
time | UTC, ISO 8601 |
level | exception, fatal, warning or notice |
class | The exception class, or the PHP error type, such as E_WARNING |
message | The message, cut after 2000 characters |
file, line | Where it was thrown or raised, relative to the Composer project or to WordPress |
twig | template:line in the Twig template, when the error comes from a view |
previous | The previous exceptions, as Class: message, up to 3 |
stack | The frames of the theme's own code in call order, then +N other frames for WordPress, plugins and packages |
method, url | The HTTP method and the request URI, or CLI and the WP-CLI command |
template | The WordPress template Føhn matched, such as single-product |
controller | The template controller that handles it, or null |
view, context | The last Twig view Timber rendered, and the keys of its context (up to 40) |
requestId | The id of the traced request, as its X-Foehn-Trace header gives it, or null. See Request Trace |
The command
| Option | Effect |
|---|---|
--limit=<n> | Print the last n entries, the newest first. Defaults to 1 |
--level=<levels> | Only these levels, separated by commas: exception,fatal |
--since=<date> | Only entries recorded at or after this date: 2026-11-12 10:00, -10 minutes, -1 hour |
--request=<id> | Only the entries of one traced request: the id wp foehn trace prints |
--format=json | Every field of each entry, as a JSON array on one line |
--clear | Delete the log |
The text cuts a message after 300 characters and gives the first 5 lines of the stack. JSON gives the whole message and every frame.
The log file
The log is wp-content/cache/foehn/errors/errors.jsonl, one JSON object per line. When the next entry would make it larger than 256 KB, it becomes errors.1.jsonl and the oldest file is deleted. The log never holds more than 3 files.
When errors are recorded
FoehnConfig::$recordErrors decides. With the default, null, errors are recorded when the environment (WP_ENVIRONMENT_TYPE) is local or development. Set it to true to record them in another environment, such as a staging site, and to false to never record them:
// app/foehn.config.php
return new FoehnConfig(
recordErrors: true,
);An entry holds paths, messages and URLs. The cache directory can be served by the web server: do not turn recording on where people you do not trust can read the files of wp-content.
How it hooks into PHP and WordPress
The recorder adds a PHP error handler, a PHP exception handler and a shutdown function, and it changes nothing in how PHP and WordPress handle the error:
- The error handler records the warning, then gives it to the handler that was there before, or to PHP.
- The exception handler records the exception, then gives it to the handler that was there before. With none, it throws the exception again, so PHP ends the request with its own fatal error.
- The shutdown function reads
error_get_last(). WordPress's fatal error handler (WP_Fatal_Error_Handler) reads the same value in its own shutdown function, which runs first, and shows its error page as usual.
Browser errors
The error log holds the errors of PHP. The errors of the JavaScript that runs in the page go to the browser console, which an agent in a terminal cannot read. While npm run dev runs, the Vite dev server writes them to a log in the theme, and wp foehn errors --browser prints them:
wp foehn errors --browserTypeError: card is null
error at 2026-11-12 15:48:50 UTC in theme/assets/js/components/Card.ts:12
theme/assets/js/components/Card.ts:12 Card.mounted()
theme/assets/js/app.js:4
+3 other framesHow it works
Vite 8 has the server.forwardConsole option: the Vite client in the page sends the console errors and warnings, the uncaught errors and the unhandled promise rejections to the dev server, which prints them in its terminal. Vite turns it on only when it runs inside a coding agent. The agent that edits the theme usually does not run npm run dev itself, and it cannot read the terminal of another process. So @studiometa/foehn-vite-plugin turns the option on, and also writes each event to dist/browser-errors.jsonl in the theme, beside the hot file. The PHP page loads the Vite client from the URL in the hot file, so this works for the pages WordPress renders, opened on the DDEV URL or on the Vite URL.
It needs Vite 8. With Vite 6 or 7, the page sends nothing and the log stays empty. Set server.forwardConsole: false in vite.config.js to turn off the terminal output and the log.
The fields of an entry
| Field | Content |
|---|---|
time | UTC, ISO 8601 |
level | error (uncaught error), rejection (unhandled promise rejection) or console (a console call) |
class | The error name, such as TypeError, or the console method, such as console.warn |
message | The message, cut after 2000 characters |
file, line | The first frame of the project's own code, relative to the Vite root, with the line of the source file |
stack | The frames of the project's own code (8 at most), then +N other frames for dependencies and other origins |
Lines are the lines of the source file: the plugin maps them back through the source map of the module, so a TypeScript or Vue file gives the line you edit. A console call has no stack, and an entry has no URL: Vite does not send the page.
The command
--browser reads the browser log in place of the error log. --limit, --since, --format=json and --clear work as for the error log. --level takes error, rejection and console. --request does not apply: a browser entry has no request id.
The log is in the dist directory of the active (parent) theme, where ViteManifest::fromTheme() reads the hot file. It has the cap of the error log: 3 files of 256 KB. npm run build empties dist, and the log with it. An entry holds console messages, and the web server can serve dist: the log exists only where the dev server runs.
The debug log
The error log holds the errors of the theme's own code. A warning of WordPress, a plugin or a package, an error_log() message and an error raised before the theme boots go to the debug log of WordPress. wp foehn log reads it as entries, and groups the entries that repeat.
wp foehn logUndefined variable $price
warning ×12 at 2026-11-12 10:42:13 UTC in theme/app/Controllers/ProductController.php:24, first at 2026-11-12 10:00:00 UTC
Uncaught RuntimeException: Boom
fatal at 2026-11-12 10:00:05 UTC in theme/app/Foo.php:12
#0 web/wp/wp-includes/class-wp-hook.php(324): App\Foo->run()
#1 web/wp/wp-includes/plugin.php(517): WP_Hook->do_action()
#2 theme/functions.php(8): do_action()
+2 more linesWhich file it reads
WordPress writes the log when WP_DEBUG and WP_DEBUG_LOG are on: wp_debug_mode() points PHP's error_log setting at wp-content/debug.log, or at the path WP_DEBUG_LOG holds. So the file holds PHP's warnings, notices, deprecations and fatal errors, and the error_log() messages of WordPress, plugins and the theme. The wp-config.php of a Føhn project sets WP_DEBUG_LOG to the value of WP_DEBUG: set WP_DEBUG=true in .env to turn the log on.
When WP_DEBUG_LOG is off, the command says how to turn it on and exits with an error. When WP_DEBUG is off and the file exists, it prints the entries and says that WordPress writes nothing new to the file. When the user that runs WP-CLI cannot read the file, it says so and exits with an error.
Entries and groups
An entry starts with the date PHP writes, such as [12-Nov-2026 10:00:00 UTC]. The lines without a date that follow belong to it: the stack trace of an uncaught exception, or a message of several lines such as an error_log(print_r($value, true)). Xdebug writes each frame of its stack trace with a date of its own; these frames go to the trace of the entry above.
| Level | Entries |
|---|---|
fatal | PHP Fatal error, PHP Parse error, PHP Recoverable fatal error |
warning | PHP Warning |
notice | PHP Notice, such as _doing_it_wrong() |
deprecated | PHP Deprecated |
log | A message without a PHP error type, such as an error_log() call |
Entries with the same level, message, file and line are one group. The groups seen last come first.
| Field | Content |
|---|---|
level | One of the levels above |
message | The message, without the file and line PHP adds, cut after 2000 characters |
file, line | Where PHP raised it, relative to the Composer project or to WordPress |
count | How many entries the group has |
first, last | When the first and the last entry were written, UTC, ISO 8601 |
trace | The stack trace of the last entry, up to 50 lines |
The command
| Option | Effect |
|---|---|
--limit=<n> | Print n groups. Defaults to 20 |
--level=<levels> | Only these levels, separated by commas: fatal,warning |
--since=<date> | Only entries written at or after this date: 2026-11-12 10:00, -10 minutes, -1 hour |
--grep=<text> | Only entries whose message, file or stack trace contains this text. Case does not matter |
--format=json | Every field of each group, as a JSON array on one line |
The filters apply to the entries before they are grouped, so count, first and last count only the entries they keep. The text cuts a message after 300 characters and gives the first 3 lines of a trace.
A debug log can grow to gigabytes. The command reads only the last 8 MB of the file, and says so when it cuts it: in the text, or on standard error with --format=json. Nothing deletes or rotates the file: it belongs to WordPress.