Editor: Surface debugging details in the ErrorBoundary

[Mamaduka]

What?

Closes #34482.

The editor's error boundary showed a generic sentence and copied the raw error.stack, which contains mostly React internals and says nothing about where in the editor the crash occurred. React passes a second argument to componentDidCatch with a componentStack describing the component tree at the throw site, and the boundary was discarding it.

This captures that component stack and puts it to use in three places.

• The editor.ErrorBoundary.errorLogged action now receives React's error info object as a second argument, so error tracking tools can record it.
• The "Copy error" button now produces a Markdown report containing the message, the stack trace, the component stack, and the user agent, ready to paste into a bug report.
• When SCRIPT_DEBUG is on, a collapsible panel shows the message and the component stack directly in the UI, so a developer can identify the failing component without opening the console.

Testing Instructions

1. Ensure SCRIPT_DEBUG is enabled.
2. Fake an error in the editor. See testing patch below.

Testing patch

diff --git a/packages/edit-post/src/components/layout/index.js b/packages/edit-post/src/components/layout/index.js
index 650683f3a0f..1b6da9a7f94 100644
--- a/packages/edit-post/src/components/layout/index.js
+++ b/packages/edit-post/src/components/layout/index.js
@@ -346,6 +346,29 @@ function MetaBoxesMain() {
 	);
 }
 
+// TEMP: remove. Stands in for a plugin panel that reads the store and throws
+// while rendering. Nested so the component stack has something to show.
+function TempCrashInner( { title } ) {
+	if ( title.toLowerCase().includes( 'crash' ) ) {
+		throw new TypeError(
+			`Cannot read properties of undefined (reading 'length')`
+		);
+	}
+
+	return null;
+}
+
+// TEMP: remove. Type "crash" in the post title to trigger it.
+function TempCrash() {
+	const title = useSelect(
+		( _select ) =>
+			_select( editorStore ).getEditedPostAttribute( 'title' ) ?? '',
+		[]
+	);
+
+	return <TempCrashInner title={ title } />;
+}
+
 function Layout( {
 	postId: initialPostId,
 	postType: initialPostType,
@@ -556,6 +579,8 @@ function Layout( {
 			<Tooltip.Provider>
 				<ThemeProvider isRoot color={ { primary: adminPrimary } }>
 					<ErrorBoundary canCopyContent>
+						{ /* TEMP: remove. */ }
+						<TempCrash />
 						<WelcomeGuide postType={ currentPostType } />
 						<div { ...navigateRegionsProps }>
 							<Editor

Testing Instructions for Keyboard

Same.

Screenshots or screencast

Post Editor	Site Editor

Use of AI Tools

Assisted by Claude.

[Mamaduka]

@jasmussen, @fcoveram, can I ask for help with design?

I used EmptyState because I saw that the boot package was using it. Not sure if it fits here. Should I just use the proposed design from the issue - #34482 (comment)?

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: karmatosed <karmatosed@git.wordpress.org>
Co-authored-by: javierarce <javiarce@git.wordpress.org>
Co-authored-by: talldan <talldanwp@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: +5.73 kB (+0.07%)

Total Size: 7.75 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	537 kB	+5.52 kB (+1.04%)
build/styles/editor/style-rtl.css	32 kB	+47 B (+0.15%)
build/styles/editor/style-rtl.min.css	27.3 kB	+58 B (+0.21%)
build/styles/editor/style.css	32 kB	+47 B (+0.15%)
build/styles/editor/style.min.css	27.3 kB	+56 B (+0.21%)

_{compressed-size-action}

[ramonjd]

Thanks for getting this started. It's working well for me functionally speaking.

I keep fullscreen on so it made me ask myself whether we need to give users an in-editor option to navigate away in that situation. I know there's the wpadminbar so maybe too much?

Idea (not actionable!!): just throwing it out there, it might be cool to see the error straight away, e.g.,

Not very user friendly though. Maybe it could be collapsible. (Show error details button or something)

[ramonjd]

Wondering if this could be confused with "contents" of the error. Maybe it could be explicit, e.g., "Copy post content" or "editor content".

Or maybe we could tweak the description to explain the option. 🤷🏻

[ramonjd]

I had to set title to null to get things to crash. Might be just me.

[Mamaduka]

Noting that I need to remove this before we land :D

[ramonjd]

❤️

[ramonjd]

Reloading might not work if the editor is crashing? What about a "Reload to try again" and/or "Exit to dashboard" buttons

[Mamaduka]

I think we had those buttons, but removed them in the last iteration. Recovery rarely worked when the error reached this boundary.

[Mamaduka]

Thanks for having a look, @ramonjd!

I like the design suggestions, especially the error report. I've improved "Component Stack" logic on a different branch; I mostly wanted to focus on design and UX here, but the idea is similar.

[jasmussen]

Thanks for the work, thanks for the ping.

This has been in need for some love for a long time, honestly, but also some rethinking. But before I can answer fully, I need to better understand the details. One of the things about the error boundary is that it is literally a boundary: everything between A and B is broken, show something in its place. And in the old designs, this boundary could also be for a single block:

I know this is different, but that's context for why both cases used the black border: it was understood to be much more compartmentalised than I think in effect it turned out to be. Because coming at this today, I like to think of it in two ways:

1. A block is broken (example above).
2. The editor is broken.

Those are two entirely different things, and should be visually different as well, in the sense that if the whole editor is broken, there's no reason to pretend any blocks are still present. We're effectively designing a crash screen instead of an error boundary.

Because of that, my instinct (but I'm curious what Francisco thinks if he chimes in) would be to show a Notice, followed by a CollapsibleCard, both of which have been designed to be able to sit next to each other. Something like:

┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ The editor has crashed                                                                                │
│                                                                                                       │
│ An unknown  error occurred. Reload to try again, or copy the error to report the problem or search.   │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Show error details                                                                                 ⌄  │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘

You'd want that somewhere in the centre of the white crashed page, not too wide.

What do you think?

[Mamaduka]

I'll try to refresh the design based on the feedback.

@jasmussen, just wanted to clarify something regarding Notice and its actions:

• "Reload to try again" - I assume this suggests a browser reload and not a specific action via a button. Right?
• Are we keeping the "Copy contents" action?
• Should I try to match the design for error details to what @ramonjd shared?

[jasmussen]

"Reload to try again" - I assume this suggests a browser reload and not a specific action via a button. Right?

Yes, I'm trying carefully to make the error message more "friend to friend" and short, but perhaps that was too short. "Reload your browser to try again" might be better after all.

Are we keeping the "Copy contents" action?

No strong opinion. If it sits inside the collapsiblecard, you're already engaging with "complexity", so it's fine. Is it actually useful? Relatedly a standard for code blocks appears to be slowly standardising on a small copy button in the top right corner of the code block itself. That's not an action item, we should probably keep this focused and simple, but something to ponder as a general question for error logs.

Should I try to match the design for error details to what @ramonjd shared?

My apologies, perhaps I had not had enough coffee when I wrote my comment, somehow I glossed over Ramon's screenshot a bit too quickly. And yes there's a lot to like there, notably around the friend-to-friend phrasings. I wonder if there's some middleground, though, that has less text?

The thing is, and this is purely anecdotal so I defer to you all: whenever I've seen this crash screen myself, I'm SOL. There's nothing I can really do but try the npm install/npm run build dance again. But I recognise that's very dev-oriented, so I actually have little instincts of how often this particular screen is seen by our users, or under which circumstances they will see it.

If the proposed steps are genuinely likely to be helpful to users, definitely include them. But let's not be exhaustive just for the sake of it. Is that helpful?

[jsnajdr]

When testing I see this, there is a lot of free space on the right:

There is an element with editor-error-boundary class, it defines max-width: 780px, and inside there is EmptyState.Root, whose .root style says max-width: var(--wpds-dimension-surface-width-sm) and that's 320px.

Is EmptyState a good component to use here? There is no empty state semantics.

In the error details, if we are showing the "Component Stack", can we also show the regular "Stack", i.e., where the error really happened, available in error.stack?

Does this need to be gated by SCRIPT_DEBUG? It's useful even on production sites, a fast way to see the error. The componentStack info should be available in production, too, it's not a dev-only feature.

As a followup, it would be nice if the BlockCrashBoundary also supported this, currently it says basically nothing about the error:

[Mamaduka]

@jasmussen, oh, sorry, I should've clarified better.

ErrorBoundary (trunk) actions:

• "Copy contents" - copies editor contents (blocks) to avoid loss.
• "Copy error" - copies the error caught by the boundary. Useful for sharing errors for debugging.

ErrorBoundary (this branch) actions:

It's also important to note that the "Show error details" toggle will be hidden in production. This is common practice.

• Do we want to retain existing actions as they are?
• Do we want a second "Copy as markdown" in the toggle area? "Copy error" will copy markdown-formatted text. Easily pasteable in the issues or LLM chats. This action will be available in production.

@jsnajdr, right. I can't design to save my life, so I shared an ugly state to get better suggestions from @jasmussen, @fcoveram 😄

In the error details, if we are showing the "Component Stack", can we also show the regular "Stack", i.e., where the error really happened, available in error.stack?

Yes, we can share as many details as we want from available data.

Does this need to be gated by SCRIPT_DEBUG? It's useful even on production sites, a fast way to see the error. The componentStack info should be available in production, too, it's not a dev-only feature.

I based this on practice used in other frameworks. WP also hides error info in production.

As a followup, it would be nice if the BlockCrashBoundary also supported this, currently it says basically nothing about the error:

Once we've established a design pattern, I'll update the remaining boundaries to match it.

[Mamaduka]

Pushed updates. Only minimal custom CSS (can't be avoided), using WP design tokens.

• Used max-width: 560px based on our dimensions system.
• Color contrast looks better in practice and, as Joen said, should pass an a11y check.
• I've included screenshots for both the Post and Site editors. The site editor has a dark background, and our error boundary adapts to it, thanks to new UI components and design tokens.

[jasmussen]

Looks good to me. I softly feel like both copy buttons should be secondary, not sure if the Notice allows this or not, so not a blocker. But IMO this is good to me. How does it feel to you?

[jsnajdr]

Some feedback:

• the "Stack" info should be before the "Component stack" info. "Stack" is the primary error stack, the component one is auxiliary and available only on some errors.
• visual design-wise, it seems odd that the entire screen is in an unified 13px font, except the "Error details" header that is 15px. It's a wp-ui/WPDS thing, a CollapsibleCard.Heading component. But it's odd that this is the only part of the UI that has a "heading" look, because it doesn't have a "heading" meaning.

The text is mono, 12px neutral-weak.

This is something that is not visible to a naked eye: the notice and the headings are 13px (font-size-md) while the text is 12px (font-size-sm). To the user this distinction is meaningless, because it's practically invisible, it's more like an inconsistency, using two font sizes instead of one.

[jasmussen]

This is something that is not visible to a naked eye: the notice and the headings are 13px (font-size-md) while the text is 12px (font-size-sm). To the user this distinction is meaningless, because it's practically invisible, it's more like an inconsistency, using two font sizes instead of one.

The motivation is that help-text is generally neutral-weak and 12px. It happens that optically the monospaced font is larger than the regular one, so it's better balanced.

However that's not critical for this juncture. If you all agree to use an inherited 13px font, I'd encourage just removing the font size override. Though if you do that, probably remove also the colour override, so that's inherited too, as it then moves away from the help-text connection.

[jsnajdr]

It happens that optically the monospaced font is larger than the regular one

That's fair, my old eyes didn't recognize at first there is a monospace font 🙂 The Apple SF sans-serif and Menlo monospace fonts don't look that different at this size.

[Mamaduka]

the "Stack" info should be before the "Component stack" info. "Stack" is the primary error stack, the component one is auxiliary and available only on some errors.

I can do the swap.

Don't have a strong opinion about font sizes. Though I like that error stack details are distinct from the body text.

[jasmussen]

I don't either have a strong opinion, but an argument for moving towards 13px black text is less CSS, and that's always good. Up to you all!

[Mamaduka]

but an argument for moving towards 13px black text is less CSS, and that's always good. Up to you all!

Two lines of CSS don't change that much 😄

[jsnajdr]

but an argument for moving towards 13px black text is less CSS

My typography education says that fewer font sizes are typically better, and that the old masters didn't have that many physical type sets anyway 🙂

[jsnajdr]

After the stack sections got swapped, my main concern is addressed and I think this is ready to ship 🚢

[Mamaduka]

• Swapped order in 5d0ea1f.
• Removed custom text styling in 80a0c40. Now it matches inherited styles as suggested.

Screenshot

[github-actions]

Flaky tests detected in 80a0c40.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/32357881604
📝 Reported tests:

Should save the changes in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js, passed after 2 failed attempts.

TimeoutError: page.waitForFunction: Timeout 10000ms exceeded.
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:34:14
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=button[name="Visual"i]')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:33:55

[jasmussen]

Nice work, thanks for doing all this.

While I'm here, can we use similar componentry for solving #62737? Or does that require a different approach?

[Mamaduka]

Technically, yes. We could use Notice with a warning variant; the component also has a speak message prop, which should resolve the issue mentioned.

One problem we might encounter here is that MultipleUsageWarning and the Warning block component are rendered inside the iframe canvas. There might be a slight chance that theme styles are affecting the components.

Here's a screenshot from a quick refactoring. I can create a PR to test tomorrow; I just need to wire up the speak for notices.

[jasmussen]

One problem we might encounter here is that MultipleUsageWarning and the Warning block component are rendered inside the iframe canvas. There might be a slight chance that theme styles are affecting the components.

Ah good catch. Also, when I test this myself, the sibling inserters sit in weird places as if the present error boundary is not actually rearranging content but is simply pushing it around. Whether we keep the Placeholder element for an error, that seems like the main thing to solve.

[jsnajdr]

One problem we might encounter here is that MultipleUsageWarning and the Warning block component are rendered inside the iframe canvas. There might be a slight chance that theme styles are affecting the components.

It's very common for blocks to show placeholder UI directly inside the editor canvas: Image, Cover, Query Loop, Columns, ... These have potentially the same problem with theme styles, but we do it anyway. Either it's solved somehow (probably not) or it's a very minor problem easy to ignore.

[andrewserong]

These have potentially the same problem with theme styles, but we do it anyway. Either it's solved somehow (probably not) or it's a very minor problem easy to ignore.

From memory we used to run into conflicts from themes from time to time and have to fix gaps (e.g. back in #58323), but we've got pretty good coverage of resets / specificity so it works pretty well nowadays. I reckon a similar approach for errors in the canvas would be okay (a bunch of resets)?

gutenberg/packages/components/src/placeholder/style.scss

Lines 5 to 42 in 0cf7ede

	// This needs specificity to override individual block styles.
	.components-placeholder.components-placeholder {
	font-size: $default-font-size;
	box-sizing: border-box;
	position: relative;
	padding: $grid-unit-30;
	width: 100%;
	text-align: left;
	margin: 0;
	color: $gray-900;
	display: flex;
	flex-direction: column;
	align-items: flex-start;
	gap: $grid-unit-20;
	// Some editor styles unset this.
	-webkit-font-smoothing: subpixel-antialiased;
	// Block UI appearance.
	border-radius: $radius-small; // Match the block toolbar material radius.
	background-color: $white;
	box-shadow: inset 0 0 0 $border-width $gray-900;
	outline: 1px solid transparent; // Shown for Windows 10 High Contrast mode.
	}
	.components-placeholder__error,
	.components-placeholder__instructions,
	.components-placeholder__label,
	.components-placeholder__fieldset {
	font-family: $default-font;
	font-size: $default-font-size;
	// Global Styles can affect this so we are resetting.
	letter-spacing: initial;
	line-height: initial;
	text-transform: none;
	font-weight: normal;
	}

[jasmussen]

An error in a Placeholder may be best, since it's in-canvas. It seems like the bigger issues to address on that other issue is the fact that it seems to mess with the flow, and the sibling inserters.