Logs and monitoring¶

Nebula writes to Magento's logger and to nothing else. No module in the set declares a log handler, a channel or a file of its own, so every line lands in the files your store already collects. Every message begins with a fixed prefix, which is what makes an alerting rule a grep.

Where the messages go¶

File	What lands there
`var/log/exception.log`	Any message logged with an `exception` entry in its context. Most Nebula failures are logged that way.
`var/log/system.log`	Everything else at info and above, including the two critical passkey messages.
`var/log/debug.log`	The `[Nebula Merger]` lines, and only while debug logging is on.

A failed save is in exception.log, not system.log

Magento's system handler diverts every record whose context carries an exception entry to exception.log and does not also write it to system.log. All the Nebula .../... failed: errors attach the exception, so each appears in exactly one file. Grep both files or you will miss half the list below.

A stock root also registers a syslog handler, but it writes nothing until dev/syslog/syslog_logging is set to 1 in app/etc/env.php. Once it is on, the same records reach the system journal under the ident Magento. Whether var/log/debug.log is written at all is Magento's dev/debug/debug_logging setting, which defaults to on in developer and default mode and off in production.

When an administrator reports a message ending "Check the admin error log", the matching line is in exception.log.

Prefixes worth an alert¶

Page someone¶

Prefix	Level	File	What happened
`Passkey verify error:`	critical	`system.log`	Admin passkey verification threw. Passkey sign-in to the admin is failing.
`Passkey customer verify error:`	critical	`system.log`	The storefront half of the same thing. Customers cannot sign in with a passkey.
`Nebula Form/Save failed:`	error	`exception.log`	A form save did not complete. The administrator saw a generic failure.
`Nebula Form/Load failed:`	error	`exception.log`	A form could not be built, so the screen came up empty.
`Nebula Form/Validate failed:`	error	`exception.log`	The validate endpoint threw rather than returning field errors.
`Nebula GridEdit/Save failed:`	error	`exception.log`	A quick-edit drawer save failed. `grid_id` and `row_id` are in the context.
`Nebula GridEdit/Panel failed:`	error	`exception.log`	The quick-edit drawer could not be opened.
`Nebula inline edit failed:`	error	`exception.log`	The row writer threw during a quick-edit save.
`Nebula Grid/Data failed:`	error	`exception.log`	A grid returned no rows and an error instead. `grid_id` is in the context.
`Nebula Grid/Export failed:`	error	`exception.log`	An export produced no file.
`Nebula CollectionProvider failed to fetch`	error	`system.log`	The collection behind a grid threw. That grid is empty for everyone.
`Nebula merchandiser: assignment write failed`	error	`exception.log`	A category product order was rolled back. Nothing was saved.
`Nebula: setting a customer password failed.`	error	`system.log`	An administrator set a customer password and the write threw.
`Nebula category reorder failed:`	error	`exception.log`	A category tree reorder threw. The tree is unchanged.

The two passkey lines are the ones a monitor should treat as an outage. Two more sit on the same path and belong in a daily digest rather than a page: Nebula passkey enrolment failed for admin user <id>: at error in exception.log, and Nebula Passkey: could not grant the two-factor session after a passkey sign-in: at warning in system.log, which leaves the administrator at the two-step screen after a valid passkey. See Security for what else sign-in does.

Investigate the same day, do not page¶

Prefix	Level	File	What it means
`Nebula Grid/Export for "<id>" returned N of M rows (export ceiling reached).`	warning	`system.log`	The export clamp fired. The file the merchant downloaded is incomplete. See Export.
`Nebula RouteFormMap: route claimed by multiple forms.`	warning	`system.log`	Two form definitions claim one route and one was dropped. Both ids are in the context.
`Nebula RouteFormMap: routeWhen is not an object; the form will not mount.`	warning	`system.log`	A malformed `routeWhen` guard. The form silently does not appear.
`Nebula RouteFormMap: failed to resolve form definition.`	warning	`exception.log`	A discovered form could not be loaded, so it claims no route.
`Failed to parse JSON definition file.`	warning	`system.log`	Broken JSON was skipped and the other files still loaded, so a screen renders subtly wrong rather than failing. `json_error` names the syntax problem.
`FileSystemException while loading definition file.`	warning	`exception.log`	A definition file could not be read at all. Same effect as above.
`Skipping invalid Nebula Content component definition.`	warning	`system.log`	One component definition was rejected and the rest loaded.
`Unresolved snippet @ref returned as placeholder.`	warning	`system.log`	A snippet reference points at nothing. A placeholder renders in its place.
`NebulaGrid: unknown collection alias`	warning	`system.log`	A grid names a collection alias that is not registered. The grid shows no rows. See Data providers.
`Nebula definition "<id>" declares no acl`	warning	`system.log`	A definition with no `acl` key is denied to every administrator.
Nebula grid "<id>" declares `editable` without	warning	`system.log`	An incomplete `editable` block. Quick edit is refused on that grid.
`Nebula inline edit on grid "<id>" dropped non-editable column(s):`	warning	`system.log`	A save arrived carrying columns the definition does not allow. Either a stale client or a tampered request.
`Nebula GridView/Save validation failed:` and the matching `Delete` and `SetDefault` lines	warning	`exception.log`	A saved-view write was rejected before it touched the database. Usually an invalid payload.
`Nebula media could not`	warning	`system.log`	One media operation failed on one file: trash, restore, purge, hash or thumbnail. The path is in the message and the rest of the library keeps working.
`Nebula media duplicate lookup failed:`	warning	`system.log`	The duplicate finder gave up on a file.
`Nebula merchandiser: could not invalidate the category product index`	warning	`exception.log`	The order was saved but the index was not marked stale. Reindex.
`Nebula: could not clear the must-change flag.`	warning	`system.log`	A customer who reset their own password kept the forced-change flag.

Noise, by design¶

[Nebula Merger] ... is debug output from the definition merger, one line per overlaid key. It only exists while debug logging is on, which in developer and default mode is the default. A burst of these lines is a page load, not an incident.
Nebula email editor: ... not found for preview. is a notice. Someone previewed an email template against an order, invoice, shipment, credit memo or customer that no longer exists.
Nebula: product gallery upload fell back to Magento: is info. An image upload took the core path instead of Nebula's.

The category tree warnings¶

Three warnings come from the guards around the category tree, and all three mean the tree was protected rather than damaged.

Nebula: blocked move of category <id> to parent <id> means a re-parent was refused, usually an attempt to move a category to the root level. The administrator saw an error and nothing changed.

Nebula: refused to move category <id> during a save means something posted a category position through an ordinary save instead of the move endpoint. The stored position was put back, so the tree is intact, but the request that did it is worth tracing: a third-party module or an integration is writing parent_id, path or level where it should not. The listed field changes are what it tried to write. The sentence at the end of that message points at an internal reference and carries nothing you need.

Nebula: category <id> is stored inconsistently means the row itself disagrees with its own path, so the guard left it alone. The message names the command to run:

bin/magento nebula:catalog:fix-category-tree --dry-run

See nebula:catalog:fix-category-tree.

Grep recipes¶

Everything Nebula wrote

grep -hE 'Nebula|Passkey' var/log/system.log var/log/exception.log

Failures only, which is the paging list

grep -hE 'Passkey (customer )?verify error|Nebula [A-Za-z]+/[A-Za-z]+ failed|Nebula (inline edit|category reorder|merchandiser: assignment write) failed|Nebula CollectionProvider failed to fetch|Nebula: setting a customer password failed' \
  var/log/system.log var/log/exception.log

Exports the merchant received incomplete

grep 'export ceiling reached' var/log/system.log

Two rules cover most of the paging table: Passkey (customer )?verify error at critical, and Nebula [A-Za-z]+/[A-Za-z]+ failed at error. Five prefixes do not fit that shape and need the longer alternation in the recipe above: Nebula inline edit failed, Nebula CollectionProvider failed to fetch, Nebula merchandiser: assignment write failed, Nebula: setting a customer password failed and Nebula category reorder failed. Everything else in this page is a warning or below and belongs in a daily digest.

What Nebula does not log¶

An ordinary access denial. A definition whose acl resource the role lacks is refused with no line written. Only a definition that declares no acl at all is logged.
Anything on the happy path. A grid that loads, a form that saves and a definition that resolves write nothing at all, so a quiet log is the normal state and not evidence that logging is broken.

Before opening a support request, run bin/magento nebula:doctor and include its output beside the log lines. Troubleshooting maps the most common of these messages to a fix.