update: error handler and trigger error handler (#1057)

* update

* update

* update

Author: dieriba

changelog/2025-07-11-trigger-error-handlers/index.md

@@ -0,0 +1,16 @@
+---
+slug: trigger-error-handlers
+version: v1.505.0
+title: Trigger error handlers
+tags: ['Error handling', 'Triggers', 'Workspace']
+description: Trigger error handlers now allow you to configure specific error handling for individual triggers. Override workspace error handlers with custom, Slack, Teams, or email notifications per trigger.
+features:
+  [
+    'Configure error handlers for individual triggers (HTTP routes, Webhooks, Kafka, SQS, WebSocket, Postgres, NATS, MQTT, GCP, Email)',
+    'Override workspace error handlers with trigger-specific handling',
+    'Support for custom scripts, Slack, Teams, and email error handlers',
+    'Additional arguments and retry configuration for custom error handlers',
+    'Works with scripts only (not flows)'
+  ]
+docs: /docs/core_concepts/error_handling#trigger-error-handlers
+---

changelog/2025-08-08-email-error-handlers/index.md

@@ -0,0 +1,16 @@
+---
+slug: email-error-handlers
+version: v1.520.0
+title: Email error handlers
+tags: ['Error handling', 'Email', 'Workspace']
+description: Email error handlers are now available for workspace and trigger error handling. Send automated error notifications via email when jobs fail, supporting multiple recipients and integration with existing error handling workflows.
+features:
+  [
+    'Email error handlers for workspace-level error notifications',
+    'Support for multiple email recipients with validation',
+    'Available for both workspace and trigger-specific error handling',
+    'Integration with existing Slack, Teams, and custom error handlers',
+    'Self-hosted instances only (requires SMTP configuration)'
+  ]
+docs: /docs/core_concepts/error_handling#email-error-handler
+---

docs/advanced/17_email_triggers/index.mdx

@@ -87,4 +87,8 @@ export async function main(sender_address: string, email_body: string) {
 
 From a script or flow [deployed](../../core_concepts/0_draft_and_deploy/index.mdx) page, you will find on the "Details & Triggers" - "Email" tab the email address to use.
 
-![Trigger panel](./trigger_panel.png "Trigger panel")
+![Trigger panel](./trigger_panel.png "Trigger panel")
+
+## Error handling
+
+Email triggers support local error handlers that override workspace error handlers for specific triggers. See the [error handling documentation](../../core_concepts/10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.

docs/core_concepts/10_error_handling/index.mdx

@@ -2,7 +2,7 @@ import DocCard from '@site/src/components/DocCard';
 
 # Error handling
 
-There are 5 ways to do error handling in Windmill.
+There are multiple ways to handle errors in Windmill.
 
 ## try/catch inside a script
 
@@ -94,11 +94,18 @@ You can pick the Slack pre-set schedule error handler or define your own.
 
 ## Workspace error handler
 
-Define a script or flow to be executed automatically in case of error in the workspace (e.g. a scheduled job fails to re-schedule).
+Configure automatic error handling for workspace-level errors (e.g. scheduled job failures, trigger failures without their own error handlers). Choose from built-in notification options or define custom error handling logic.
 
-### Workspace error handler on Slack and Microsoft Teams
+Configure workspace error handlers from **Workspace Settings > Error Handler** tab. The system supports four types of error handlers:
 
-On [Cloud plans and Self-Hosted & Enterprise Edition](/pricing), you can [connect workspace to Slack](../../integrations/slack.mdx) or [Microsoft Teams](../../integrations/teams.mdx) and enable an automated error handler on a given channel.
+### Slack error handler
+
+Send error notifications to Slack channels. Requires workspace to be [connected to Slack](../../integrations/slack.mdx).
+
+**Configuration:**
+- Enable/disable Slack error handler toggle
+- Specify Slack channel (without # prefix)
+- Available on [Cloud plans and Self-Hosted & Enterprise Edition](/pricing)
 
 <iframe
 	style={{ aspectRatio: '16/9' }}
@@ -110,49 +117,162 @@ On [Cloud plans and Self-Hosted & Enterprise Edition](/pricing), you can [connec
 	className="border-2 rounded-lg object-cover w-full dark:border-gray-800"
 ></iframe>
 
-<br />
+### Microsoft Teams error handler
 
-### Custom workspace error handler
+Send error notifications to Microsoft Teams channels. Requires workspace to be [connected to Teams](../../integrations/teams.mdx).
 
-You can also define a custom script or flow to be executed automatically in case of error in the workspace.
+**Configuration:**
+- Enable/disable Teams error handler toggle
+- Select from available Teams channels dropdown
+- Available on [Cloud plans and Self-Hosted & Enterprise Edition](/pricing)
 
-From the workspace settings, on the "Error handler" tab and pick a script or flow.
+### Email error handler
 
-![Workspace Error handler](./workspace_error_handler.png 'Workspace Error handler')
+Send error notifications via email to specified recipients.
 
-The following args will be passed to the error handler:
+**Configuration:**
+- Specify email addresses to receive error notifications
+- Only available on Self-Hosted instances (not available on Cloud)
+- Requires SMTP configuration
 
-- path: The path of the script or flow that errored.
-- email: The email of the user who ran the script or flow that errored.
-- error: The error details.
-- job_id: The job id.
-- is_flow: Whether the error comes from a flow.
-- workspace_id: The workspace id of the failed script or flow.
+### Custom error handler
 
-The Error handler will be executed by the automatically created group g/error_handler. If your error handler requires variables or resources, you need to add them to the group.
+Execute custom scripts or flows as error handlers for advanced error handling logic.
 
-Here is a template for your workspace error handler:
+**Configuration:**
+- Script or flow selection via script picker
+- Additional arguments can be configured if the chosen script or flow has parameters
+- Template creation options
+
+**Parameters passed to custom error handlers:**
+
+All custom workspace error handlers receive the following base parameters:
+
+- `workspace_id`: The workspace id where the error occurred
+- `job_id`: The job id of the failed execution
+- `path`: The path of the script or flow that errored
+- `is_flow`: Whether the error comes from a flow
+- `started_at`: When the failed job started
+- `email`: The email of the user who ran the script or flow that errored
+- `schedule_path`: The schedule path (only present if the error comes from a scheduled job)
+
+**Custom error handler template:**
 
 ```ts
-// Workspace error handler template
+// Custom workspace error handler template
 
 export async function main(
+	workspace_id: string, // The workspace id where the error occurred
+	job_id: string, // The job id of the failed execution
 	path: string, // The path of the script or flow that errored
+	is_flow: boolean, // Whether the error comes from a flow
+	started_at: string, // When the failed job started
 	email: string, // The email of the user who ran the script or flow that errored
-	error: object, // The error details
-	job_id: string, // The job id
+	schedule_path?: string // The schedule path (only present if error from scheduled job)
+) {
+	const run_type = is_flow ? 'flow' : 'script';
+	console.log(
+		`Workspace error: ${run_type} ${path} run by ${email} failed in workspace ${workspace_id}`
+	);
+	console.log(`Job ${job_id} started at ${started_at}`);
+	
+	if (schedule_path) {
+		console.log(`Scheduled job from: ${schedule_path}`);
+	}
+	
+	// Add your custom error handling logic here
+	// Examples: send to external monitoring, create incidents, etc.
+	
+	// Note: The actual error details are available through the job context
+	// and can be retrieved using Windmill's job APIs if needed
+	
+	return { handled: true, workspace_id, job_id };
+}
+```
+
+---
+
+From the workspace settings, go to the "Error handler" tab and select your preferred error handler type.
+
+![Workspace Error handler](./workspace_error_handler.png 'Workspace Error handler')
+
+### Error handler execution
+
+- Error handlers are executed by the automatically created group `g/error_handler`
+- If your error handler requires variables or resources, add them to the `g/error_handler` group
+- Error handlers run as different users depending on type:
+  - Custom, Slack, Teams error handlers: `[email protected]`
+  - Email error handlers: `[email protected]`
+- The system prevents infinite loops by not triggering error handlers for error handler jobs themselves
+
+### Advanced configuration
+
+**Skip error handler for cancelled jobs:**
+Enable the "Do not run error handler for canceled jobs" option to prevent error handlers from triggering when jobs are manually cancelled.
+
+
+## Trigger error handlers
+
+Each trigger type (HTTP routes, Webhooks, Kafka, SQS, WebSocket, Postgres, NATS, MQTT, GCP, Email) can have its own local error handler configured. If a trigger-specific error handler is defined, it will be used for that trigger instead of the workspace error handler. **Trigger error handlers only work for scripts** (not flows).
+
+
+### Configuring trigger error handlers
+
+When creating or editing a trigger, you can configure the same error handler options as workspace error handlers:
+- **Custom script or flow**: Execute your own custom error handling logic
+- **Slack integration**: Send error notifications to Slack channels
+- **Microsoft Teams integration**: Send error notifications to Teams channels  
+- **Email notifications**: Send error alerts via email to specified recipients
+
+For each trigger error handler, you can also specify:
+- **Error handler arguments**: Additional arguments for the custom error handler (only configurable if the chosen script or flow has parameters)
+- **Retry configuration**: Number of retries and retry strategy before invoking the error handler
+
+### Parameters passed to trigger error handlers
+
+Trigger error handlers receive the following base parameters:
+- `error`: The error details from the failed job
+- `path`: The path of the script or flow that errored
+- `is_flow`: Whether the error comes from a flow (always `false` for triggers)
+- `trigger_path`: The trigger path in format `<trigger_kind>/<trigger_path>` (e.g., `http_trigger/my-webhook`, `kafka_trigger/my-topic`)
+- `workspace_id`: The workspace id where the error occurred
+- `email`: The email of the user who triggered the execution
+- `job_id`: The job id of the failed execution
+- `started_at`: When the failed job started
+
+If using a custom trigger error handler, additional custom arguments can be passed via the error handler configuration.
+
+### Example trigger error handler
+
+Here's a template for a trigger error handler:
+
+```ts
+// Trigger error handler template
+export async function main(
+	error: object, // The error details from the failed job
+	path: string, // The path of the script or flow that errored
 	is_flow: boolean, // Whether the error comes from a flow
-	workspace_id: string // The workspace id of the failed script or flow
+	trigger_path: string, // The trigger path in format <trigger_kind>/<trigger_path>
+	workspace_id: string, // The workspace id where the error occurred
+	email: string, // The email of the user who triggered the execution
+	job_id: string, // The job id of the failed execution
+	started_at: string // When the failed job started
 ) {
 	const run_type = is_flow ? 'flow' : 'script';
 	console.log(
-		`An error occurred with ${run_type} ${path} run by ${email} in workspace ${workspace_id}`
+		`Trigger error: ${run_type} ${path} run by ${email} failed in workspace ${workspace_id}`
 	);
-	console.log(error);
+	console.log(`Trigger: ${trigger_path}, Job ID: ${job_id}, Started: ${started_at}`);
+	console.log('Error details:', error);
+	
+	// Add custom logic for trigger-specific error handling
+	
 	return error;
 }
 ```
 
+This allows you to customize error handling behavior per trigger while maintaining consistent fallback to workspace-level error handling.
+
 ## Instance error handler
 
 You can define a script to be executed automatically in case of error in your instance (all workspaces).

docs/core_concepts/10_error_handling/workspace_error_handler.png

@@ -397,4 +397,8 @@ async function verifySignature(signature: string, body: string, timestamp?: stri
   }
 }
 ```
-> ℹ️ When using **Custom Script**, the `raw_body` option is automatically enabled.
+> ℹ️ When using **Custom Script**, the `raw_body` option is automatically enabled.
+
+## Error handling
+
+HTTP routes support local error handlers that override workspace error handlers for specific routes. See the [error handling documentation](../10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.

docs/core_concepts/10_error_handling/workspace_error_handler.png.webp

@@ -86,6 +86,10 @@ Windmill supports the following filter:
 
 ![Filters](./filters.png 'Filters')
 
+## Error handling
+
+WebSocket triggers support local error handlers that override workspace error handlers for specific triggers. See the [error handling documentation](../10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.
+
 
 
 

docs/core_concepts/39_http_routing/index.mdx

@@ -56,3 +56,7 @@ export async function main(message_content: string, topic: string) {
   // do something with the message content and topic
 }
 ```
+
+## Error handling
+
+Kafka triggers support local error handlers that override workspace error handlers for specific triggers. See the [error handling documentation](../10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.

docs/core_concepts/40_websocket_triggers/index.mdx

@@ -76,3 +76,7 @@ A [durable push-consumer](https://docs.nats.io/nats-concepts/jetstream/consumers
 If one already exists, it will be overwritten.
 The consumer name is also used as the `DeliverSubject`, so make sure it's unique.
 
+## Error handling
+
+NATS triggers support local error handlers that override workspace error handlers for specific triggers. See the [error handling documentation](../10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.
+