Skip to content

Request Trace ​

In the local and development environments, each front-end request stores what it ran, and wp foehn trace prints it: the template files WordPress tried, the one it found, the controller, the Twig views with their context providers and keys, the blocks, the query count, the time and the errors of the request. Use it when a page renders the wrong template, the wrong view or the wrong data.

bash
wp foehn trace /
GET / · 200 · 669 ms · 16 queries
  trace 238fc0 at 2026-11-12 14:24:12 UTC
template
  tried front-page.php, home.php, index.php
  found web/wp-content/themes/starter-theme/index.php
  matched front-page · controller App\Controllers\ArchiveController
views
  pages/archive.twig
    providers App\ContextProviders\GlobalContextProvider
    context site, theme, user, http_host, wp_title, body_class, menus, post, posts, pagination, … (+4)
  sections/posts.twig
    providers App\ContextProviders\GlobalContextProvider
    context site, theme, user, http_host, wp_title, body_class, menus, post, posts, pagination, … (+4)
blocks
  core/paragraph
Every field: wp foehn trace 238fc0 --format=json.

The command ​

Argument or optionEffect
<path>, <url>Request this page of the site, then print its trace: /about/, or a URL of the site
lastThe trace of the last traced request, such as the page a browser loaded. The default
<id>The trace of one request: the 6 characters of its X-Foehn-Trace response header
listThe last traced requests, one per line: id, time, status, duration, method and URL. --limit=<n>, 10 by default
--format=jsonEvery field of the trace, and the full error entries of the request, as JSON on one line
--clearDelete every trace

With a path, the command makes an HTTP request to the site with wp_remote_get(), as an anonymous visitor: no cookies, and no redirects followed. The trace is the one of a real request, through the web server. A redirect is traced with its status and the URL it sends to. The command only requests URLs of the site, and it does not check the certificate, because a local site often has one that WordPress does not know.

The text cuts each list after 10 items and shows 8 views and 5 errors. --format=json gives every field. wp foehn errors --request=<id> gives the errors of the request in full.

What a trace holds ​

FieldContent
id6 hexadecimal characters, sent in the X-Foehn-Trace response header
timeWhen the request ended, UTC, ISO 8601
method, urlThe HTTP method and the request URI, cut after 2000 characters
statusThe HTTP status of the response
locationThe Location header of a redirect, or null
durationMsThe time from the start of the request to its end, in milliseconds
queriesThe number of database queries (get_num_queries())
hierarchyThe template files WordPress tried, in order (the {type}_template_hierarchy filters)
templateFileThe template file WordPress found, before a template controller replaced it
templateThe WordPress template Føhn matched, such as single-product
controllerThe template controller that handles it, or null
viewsEach Twig view Timber rendered, in order: view, count, keys (the context keys, up to 40), candidates (the views renderFirst() tried, when it chose this one) and providers (the context providers that ran, in order)
blocksEach block name rendered, with the number of times
errorsIn the output of the command only: the entries of the error log with this requestId

Each list keeps at most 30 items.

Which requests are traced ​

A request is traced when WordPress sends the headers of a front-end page (the send_headers action of WP::main()). The admin, admin-ajax.php, WP-Cron, REST requests and WP-CLI do not send it, so they are not traced. /favicon.ico and /robots.txt, which a browser asks for after a page, get an id but no stored trace, so last stays the page. A file the web server serves and a page the page cache serves run no PHP, so they have no trace either: the command says so, and gives the wp foehn cache:clear --url= command to run.

The id is given when the headers are sent. An error raised before, during init for example, has no requestId. An error raised after has the id, and the trace lists it.

The store is wp-content/cache/foehn/traces, one JSON file per request. It keeps the last 100 traces and deletes the older ones.

When requests are traced ​

FoehnConfig::$traceRequests decides. With the default, null, requests are traced when the environment (WP_ENVIRONMENT_TYPE) is local or development. Set it to true to trace them in another environment, such as a staging site, and to false to never trace them:

php
// app/foehn.config.php
return new FoehnConfig(
    traceRequests: true,
);

Each traced request writes a file and sends a header. A trace holds URLs, template paths and class names, and the cache directory can be served by the web server: do not turn tracing on where people you do not trust can read the files of wp-content. The page cache does not store the X-Foehn-Trace header.

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