Skip to content

Error Page

Belikhun edited this page Sep 15, 2026 · 1 revision

🚨 Error page

When something throws, blink stores a report and shows it. The report holds the exception, the stack trace with source, and the state of the request around it: headers, routing, modules, autoload, environment, queries, timings.

Reports live under DATA_ROOT/errors as {id}.report, and the Report-ID header names the one behind the response. /error/{id} renders it again later.

What the client gets

The response follows the Accept header:

Accept Response
text/html first The error page
application/json first The API envelope, with report pointing at the page

Both carry the status, the code and the Report-ID header.

With CONFIG::$DEBUG off, the stored report keeps only the summary: the exception class, where it was thrown, and the request line. No headers, no session, no environment, no source. A report is reachable by anyone holding its id, so there is nothing sensitive in it to leak. The JSON envelope is redacted the same way: no exception section, no caller, no captured output.

On the console

A command that throws prints the same information as text on stderr: the exception, the location, the tip, the stack trace with the fault frame marked, and the report id at the bottom.

Blink\Exception\CodingError: Deliberate failure
  at /routes/web.php:14

Stack trace:
> #0  /routes/web.php:14
        Blink\Exception\CodingError()
  #1  core/classes/Essence.php:385
        App\Console\ImportOrders -> run()

Report 8daf2c816b8e621a4ebd

error:list finds it afterwards.

Tips

Some exceptions come with advice. Blink answers for its own:

Exception The tip says
ClassNotDefined The file loaded but does not define the class, with a link to open it
ClassNotFound Nothing loaded, and every path the autoloader tried
RouteNotFound The path is not handled by the server
InvalidDefinition What the class has to extend
ModuleNotFound The module is listed in CONFIG::$MODULES but could not be loaded
NotLoggedIn The page needs an authenticated session
EtherInvalidMiddleware The reference is not a class, alias or group, and where to register it
EssenceBindingNotDefined The abstract needs an Essence::bind() in a module's define()
CodingError for the user class Extend UserBase and register it with Blink::useUserClass()

An application adds its own:

use Blink\ErrorPage;

ErrorPage::addTipProvider(function (string $class, ?array $data) {
	if ($class === App\Exception\QuotaExceeded::class)
		return array( "Quota reached", "Raise the plan limit in settings." );
});

Providers run after the built-ins, so one can speak to an exception blink already answers for.

Context

The page ends with context groups: Request (path, method, status, query string, headers, body), App (routing, routes, session, modules, autoload, debug output, exception data, environments, constants, output buffer) and Metrics (requests, queries, files, a timeline of timings).

Add a group of your own:

ErrorPage::addContextProvider(function (ErrorPage $page) {
	$group = new ContextGroup("Workspace");
	$item = new ContextItem("current", "Current", Workspace::current() ?-> out(), "cube");
	$item -> setRenderer([ ContextRenderer::class, "list" ]);
	$group -> add($item);

	return array( $group );
});

Or through Ether's errorPage stage, which is the same thing wrapped in middleware and is what a module should prefer. See Ether. A provider that throws is logged and skipped: an error being reported must not be lost to a second one.

Reporting without a response

Work that fails with nobody to show a page to still files a report:

use Blink\ErrorPage;

try {
	$importer -> run();
} catch (\Throwable $e) {
	$id = ErrorPage::report($e);
	Trace::error(Trace::APP, "import.failed") -> payload(array( "report" => $id )) -> record();
}

A Ticker task that exhausts its attempts, an orbit entry that fails, and a Lightrail handler that throws all do this for you, and store the report id on the row so ticker:failed and lightrail:dispatch can point at it.

Managing reports

php core/blink error:list                  # server errors, from the index
php core/blink error:list --all            # every report file, client errors included
php core/blink error:purge --days=30
php core/blink error:purge --keep=100      # keep the newest, delete the rest

Server errors are also appended to errors/meta.ndjson, a one-line-per-report index read backwards, so listing recent failures never unserializes anything. getMetas($amount, $page) reads it from code.

Frames

ErrorPage\Inspector turns a throwable into ErrorPage\Frame objects: one per trace entry, a synthetic frame in front for the throw site itself, the previous-exception chain merged in, and duplicate frames collapsed. Frames inside blink are badged blink and frames under vendor/ are badged vendor, so the application's own code is easy to pick out. Every throw site in the chain is badged fault.

A fatal error normally traces only to the shutdown handler. When Xdebug is loaded, its function stack is used instead, so the calls that led to the fatal are visible.

Clone this wiki locally