# Monitor and debug scripts

Inspect extension runs and receive notifications when a script fails.

You can use Workbench to inspect extension runs and troubleshoot failures. For Billing extensions, you can also receive email or event notifications when a script fails.

## Understand failed Billing script runs

When a Billing script that you authored can’t complete successfully, Stripe marks the extension run as failed. Your Billing script can fail when it:

- Takes longer than 1 second to run and times out.
- Intentionally or unintentionally results in an exception.
- Returns a result that doesn’t meet the extension’s validation rules. See the documentation for the extension to learn about its validation rules.

Catch exceptions when your script can recover or return a valid fallback result. When your Billing script fails, Stripe defaults to standard functionality for the operation that caused the failure.

Errors in Stripe-authored scripts and Stripe infrastructure errors cause the request to return an HTTP 500 response.

For custom action failure behavior, see [Timeouts and retries](https://docs.stripe.com/extensions/custom-actions/build-with-script.md#timeouts-and-retries).

## Inspect extension runs in Workbench

Workbench shows the status, input, output, and error details for your extension runs.

1. Open [Extension runs](https://dashboard.stripe.com/workbench/extension-runs) in Workbench.
2. Review the recent runs and their statuses and timestamps.
3. Select a failed run to inspect its input, output, and error details.

For more information, see [View extension run details](https://docs.stripe.com/workbench/guides.md#view-extension-runs).

## Receive notifications for Billing script failures

Failure notifications are only available for Billing extensions.

### Receive failure emails

By default, Stripe sends an email to the account where the extension is installed when a Billing script fails. The email describes the effect of the failure and links to the failed extension run in Workbench. Recipients can disable **Extension run failures** in their [communication preferences](https://dashboard.stripe.com/settings/communication-preferences#account).

To avoid sending an email for every failed run, Stripe sends at most one email for the same extension per UTC calendar day. Stripe tracks failures in live mode separately from failures in sandboxes.

### Receive failures in real time

For real-time notifications, subscribe to the [`v2.extend.extension_run.failed`](https://docs.stripe.com/api/v2/core/events/event-types.md?api-version=2026-07-29.preview#v2_event_types-v2.extend.extension_run.failed) event. [Set up an event destination](https://docs.stripe.com/events/set-up-events.md) that subscribes to this event, then process the event in your application or use it to trigger a [Workflow](https://docs.stripe.com/workflows.md).

The event destination sends a thin event. Retrieve the full event from `/v2/core/events/{id}` before processing it. The full event identifies the failed extension run and includes extension and error details. Follow the full event’s Workbench URL to investigate the failed run.

## See also

- [How extensions work](https://docs.stripe.com/extensions/how-extensions-work.md)
- [Build a prorations extension with a script](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)
- [Build a custom action with a script](https://docs.stripe.com/extensions/custom-actions/build-with-script.md)
- [Handle endpoint errors in a script](https://docs.stripe.com/extensions/handle-errors.md)