error overlay: show `cause` if available (#6052)

* show `cause` in error overlay

* add extra check for string

* add changeset

3 files changed, 33 insertions, 3 deletions

diff --git a/.changeset/clever-panthers-end.md b/.changeset/clever-panthers-end.md
new file mode 100644
index 000000000..ac52a0bfb
--- /dev/null
+++ b/.changeset/clever-panthers-end.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Error overlay will now show the error's `cause` if available.
diff --git a/packages/astro/src/core/errors/dev/vite.ts b/packages/astro/src/core/errors/dev/vite.ts
index 57aad4e8a..4cc430ff6 100644
--- a/packages/astro/src/core/errors/dev/vite.ts
+++ b/packages/astro/src/core/errors/dev/vite.ts
@@ -118,6 +118,7 @@ export interface AstroErrorPayload {
 			line?: number;
 			column?: number;
 		};
+		cause?: unknown;
 	};
 }
 
@@ -174,6 +175,7 @@ export async function getViteErrorPayload(err: ErrorWithMetadata): Promise<Astro
 			},
 			plugin,
 			stack: err.stack,
+			cause: err.cause
 		},
 	};
 
diff --git a/packages/astro/src/core/errors/overlay.ts b/packages/astro/src/core/errors/overlay.ts
index e208017a9..0e3f76b00 100644
--- a/packages/astro/src/core/errors/overlay.ts
+++ b/packages/astro/src/core/errors/overlay.ts
@@ -321,7 +321,8 @@ const style = /* css */ `
 
 #message-hints,
 #stack,
-#code {
+#code,
+#cause {
   border-radius: var(--roundiness);
   background-color: var(--box-background);
 }
@@ -471,7 +472,8 @@ const style = /* css */ `
   color: var(--error-text);
 }
 
-#stack h2 {
+#stack h2,
+#cause h2 {
   color: var(--title-text);
   font-family: var(--font-normal);
   font-size: 22px;
@@ -480,7 +482,8 @@ const style = /* css */ `
   border-bottom: 1px solid var(--border);
 }
 
-#stack-content {
+#stack-content,
+#cause-content {
   font-size: 14px;
   white-space: pre;
   line-height: 21px;
@@ -488,6 +491,10 @@ const style = /* css */ `
   padding: 24px;
   color: var(--stack-text);
 }
+
+#cause {
+  display: none;
+}
 `;
 
 const overlayTemplate = /* html */ `
@@ -552,6 +559,11 @@ ${style.trim()}
       <h2>Stack Trace</h2>
       <div id="stack-content"></div>
     </section>
+
+    <section id="cause">
+      <h2>Cause</h2>
+      <div id="cause-content"></div>
+    </section>
   </div>
 </div>
 `;
@@ -593,6 +605,17 @@ class ErrorOverlay extends HTMLElement {
 		this.text('#title', err.title);
 		this.text('#message-content', err.message, true);
 
+    const cause = this.root.querySelector<HTMLElement>('#cause');
+    if (cause && err.cause) {
+      if (typeof err.cause === 'string') {
+        this.text('#cause-content', err.cause);
+        cause.style.display = 'block';
+      } else {
+        this.text('#cause-content', JSON.stringify(err.cause, null, 2));
+        cause.style.display = 'block';
+      }
+    }
+
 		const hint = this.root.querySelector<HTMLElement>('#hint');
 		if (hint && err.hint) {
 			this.text('#hint-content', err.hint, true);