Debugging Magento errors with Bricklayer diagnose-error

Just enough debugging setup to get from “something broke” to a fix in one tool call.

The usual routine: tail var/log/exception.log, read the stack trace, figure out which module threw it, check if it is enabled, look for plugins on the class, check deploy mode, caches, indexers, generated code. Every step is a separate command, and an AI agent doing it by hand burns a lot of context on it.

diagnose-error does all of it at once. It reads the exception, finds the responsible module, pulls DI preferences and plugins for the failing class, checks the environment, counts how often the error happens and returns fix suggestions with CLI commands. It recognizes 15 common Magento error patterns, including class-not-found, DI compilation errors, database issues, search engine failures, invalid templates or blocks, memory exhaustion and session errors.

Parameters and response

All parameters are optional, the defaults diagnose the most recent exception from the last hour:

diagnose-error(index=0, source="exception", since="1h", pattern="", verbosity="standard")

Parameter	Default	Description
`index`	`0`	Which error to diagnose (0 = most recent)
`source`	`exception`	Log file: exception, system, debug, cron
`since`	`1h`	Time window: 5m, 1h, 24h, 7d
`pattern`	`""`	Substring filter for error messages
`verbosity`	`standard`	minimal, standard, detailed

What comes back:

error - exception class, message, file, line, stack trace and chained previous exception
module_context - responsible module, version, enabled status, dependencies, validation issues
di_context - preferences and plugins for the failing class
environment - deploy mode, disabled caches, invalid indexers, generated code age
history - error frequency and top exception types, counted from the log the error actually came from
suggestions - fixes with confidence (high/medium/low) and CLI commands
_hint - only when plugins or DI are involved, points to plugin-list or di-configuration

Workflow

Let’s assume a customer reports checkout failing “sometime this morning”.

Get the big picture first, what has been failing and how often:

log action="analyze" hours=24

Diagnose the one You care about, filtered by message:

diagnose-error since="24h" pattern="Quote"

Not the right one? Step back through older errors with index=1, index=2…
Cron job failing silently? diagnose-error source="cron"
If _hint points to plugin-list or di-configuration, follow it, the problem is likely someone else’s plugin or a preference
Need the raw log around it? Read with a filter and cap long entries:

log action="read" logType="exception" lines=200 filter="Quote" max_entry_length=500

`log` parameter	Default	Used by
`action`	required	`read`, `list`, `search`, `analyze`
`logType`	`system`	read
`lines` / `filter`	`100` / `""`	read
`query` / `maxResults`	`""` / `50`	search
`hours`	`24`	analyze
`max_entry_length`	`0` (no limit)	all

Applied a fix with setup:upgrade or setup:di:compile? Bricklayer reinitializes itself on the next call, so a fresh diagnose-error reflects the new state.

Start coding!

Source: GitHub · Logs & diagnostics wiki