diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx
index 17c1d80e8acee6..1f60c2fc63a4f9 100644
--- a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx
+++ b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx
@@ -564,6 +564,7 @@ You can customize the Crash-Report modal to your organization's needs, for examp
 | `successMessage` | Your feedback has been sent. Thank you!                                                              |
 | `onLoad`         | n/a - (**An optional callback that will be invoked when the widget opens.**)                         |
 | `onClose`        | n/a - (**An optional callback that will be invoked when the widget closes.**)                        |
+| `onError`        | n/a - (**An optional callback that receives an `Error` if the dialog cannot be shown.**)        |
 
 The optional callback `onLoad` will be called when users see the widget. You can use this to run custom logic, for example to log an analytics event:
 
@@ -572,3 +573,12 @@ The optional callback `onLoad` will be called when users see the widget. You can
 The optional callback `onClose` will be called when users close the widget. You can use this to run custom logic, for example to reload the page:
 
 <PlatformContent includePath="user-feedback/example-widget-onclose/" />
+
+The dialog cannot open without an event ID or if its script fails to load. Use the optional `onError` callback to handle these failures. It receives an `Error` with one of these messages:
+
+- `No event ID to show the report dialog for`: Neither the `eventId` option nor `Sentry.lastEventId()` provides an event ID.
+- `Failed to load the report dialog script`: The script failed to load, for example, because of an ad blocker or network problem.
+
+<PlatformContent includePath="user-feedback/example-widget-onerror/" />
+
+The `onError` callback handles failures when opening the dialog, not errors when submitting a report.
diff --git a/platform-includes/user-feedback/example-widget-onerror/javascript.mdx b/platform-includes/user-feedback/example-widget-onerror/javascript.mdx
new file mode 100644
index 00000000000000..2db2a0a5e2a88e
--- /dev/null
+++ b/platform-includes/user-feedback/example-widget-onerror/javascript.mdx
@@ -0,0 +1,11 @@
+```javascript
+Sentry.showReportDialog({
+  // ...
+  onError(error) {
+    console.error(error.message);
+    window.alert(
+      "The report form could not load. Check your connection or ad blocker settings and try again."
+    );
+  },
+});
+```