Skip to content

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.

AttributeWhat 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.phpThe 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 problems

wp foehn inspect problems prints each one in full, and --format=json gives class, attribute, reason and fix for each row:

bash
wp foehn inspect problems --format=json
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.

bash
wp foehn errors
Studiometa\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 frames

What 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 vendor and node_modules directories 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 ​

FieldContent
timeUTC, ISO 8601
levelexception, fatal, warning or notice
classThe exception class, or the PHP error type, such as E_WARNING
messageThe message, cut after 2000 characters
file, lineWhere it was thrown or raised, relative to the Composer project or to WordPress
twigtemplate:line in the Twig template, when the error comes from a view
previousThe previous exceptions, as Class: message, up to 3
stackThe frames of the theme's own code in call order, then +N other frames for WordPress, plugins and packages
method, urlThe HTTP method and the request URI, or CLI and the WP-CLI command
templateThe WordPress template Føhn matched, such as single-product
controllerThe template controller that handles it, or null
view, contextThe last Twig view Timber rendered, and the keys of its context (up to 40)
requestIdThe id of the traced request, as its X-Foehn-Trace header gives it, or null. See Request Trace

The command ​

OptionEffect
--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=jsonEvery field of each entry, as a JSON array on one line
--clearDelete 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:

php
// 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:

bash
wp foehn errors --browser
TypeError: 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 frames

How 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 ​

FieldContent
timeUTC, ISO 8601
levelerror (uncaught error), rejection (unhandled promise rejection) or console (a console call)
classThe error name, such as TypeError, or the console method, such as console.warn
messageThe message, cut after 2000 characters
file, lineThe first frame of the project's own code, relative to the Vite root, with the line of the source file
stackThe 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.

bash
wp foehn log
Undefined 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 lines

Which 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.

LevelEntries
fatalPHP Fatal error, PHP Parse error, PHP Recoverable fatal error
warningPHP Warning
noticePHP Notice, such as _doing_it_wrong()
deprecatedPHP Deprecated
logA 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.

FieldContent
levelOne of the levels above
messageThe message, without the file and line PHP adds, cut after 2000 characters
file, lineWhere PHP raised it, relative to the Composer project or to WordPress
countHow many entries the group has
first, lastWhen the first and the last entry were written, UTC, ISO 8601
traceThe stack trace of the last entry, up to 50 lines

The command ​

OptionEffect
--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=jsonEvery 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.

Føhn is released under the GPL-3.0-or-later license. The starter, the installer and the Vite plugin are MIT.