> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution Timeout Administration Guide

> The Execution Timeout & Watchdog feature automatically detects and handles workflow executions that exceed their configured deadline. A background watchdog (pg…

## Overview

The Execution Timeout & Watchdog feature automatically detects and handles workflow executions that exceed their configured deadline. A background watchdog (pg\_cron) periodically scans for overdue executions and applies the configured timeout behavior.

***

## Configuration

### Global Settings (FW Settings Page)

Navigate to **Settings → Forms & Workflow → Timeouts** tab to configure:

| Setting                    | Default | Range  | Description                                         |
| -------------------------- | ------- | ------ | --------------------------------------------------- |
| Execution Timeout Watchdog | Off     | On/Off | Enable/disable automatic timeout detection          |
| Default Timeout (Minutes)  | 60      | 1–1440 | Default maximum execution duration                  |
| Warning Threshold (%)      | 80      | 50–99  | Percentage at which warning notifications are sent  |
| Check Interval (Minutes)   | 5       | 1–60   | How often the watchdog scans for overdue executions |

### Per-Workflow Settings (Workflow Editor)

Each workflow definition can override timeout settings via the **Timeout Configuration** panel in the workflow editor:

| Setting                | Default | Description                                                    |
| ---------------------- | ------- | -------------------------------------------------------------- |
| Enable Timeout         | Off     | Override global setting for this workflow                      |
| Max Duration (Minutes) | 60      | Maximum allowed execution time                                 |
| Warning Threshold (%)  | 80      | When to send at-risk warnings                                  |
| On Timeout             | Fail    | Action when deadline exceeded: `Fail`, `Cancel`, or `Escalate` |

***

## Timeout Behaviors

| Behavior     | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| **Fail**     | Sets execution status to `timed_out`, records error, routes to DLQ            |
| **Cancel**   | Sets execution status to `cancelled`, records timeout reason                  |
| **Escalate** | Sets execution status to `timed_out`, sends escalation notification to admins |

***

## Deadline Extension

Administrators with `fw.workflows.admin` permission can extend a running execution's deadline:

1. Open the execution detail dialog
2. Click the **Extend** button next to the deadline indicator
3. Enter the extension duration (1–1440 minutes) and a reason (minimum 5 characters)
4. Click **Extend Deadline**

The extension resets the warning notification flag, allowing a new warning to be sent if the execution approaches the new deadline.

***

## Monitoring

### Execution Detail View

The deadline indicator shows real-time status:

| Status          | Color           | Description                                  |
| --------------- | --------------- | -------------------------------------------- |
| **On Track**    | Green           | Execution is within safe time limits         |
| **At Risk**     | Yellow/Warning  | Execution has exceeded the warning threshold |
| **Expired**     | Red/Destructive | Execution has exceeded its deadline          |
| **No Deadline** | Gray            | No timeout configured                        |

### Notifications (PF-10)

The watchdog sends two types of notifications:

1. **Timeout Warning** — Sent once when an execution reaches the warning threshold
2. **Execution Timed Out** — Sent when an execution is terminated due to timeout

***

## pg\_cron Setup

The watchdog requires a pg\_cron job to be registered. This is **not** included in migrations (contains environment-specific values). Register via the SQL Editor:

```sql theme={null}
SELECT cron.schedule(
  'workflow-timeout-watchdog',
  '*/5 * * * *',
  $$
  SELECT net.http_post(
    url := 'https://<PROJECT_REF>.supabase.co/functions/v1/workflow-timeout-checker',
    headers := '{"Content-Type": "application/json", "Authorization": "Bearer <ANON_KEY>"}'::jsonb,
    body := concat('{"time": "', now(), '"}')::jsonb
  ) AS request_id;
  $$
);
```

Replace `<PROJECT_REF>` and `<ANON_KEY>` with your project values.

***

## Troubleshooting

| Issue                     | Check                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Watchdog not running      | Verify pg\_cron job exists: `SELECT * FROM cron.job WHERE jobname = 'workflow-timeout-watchdog'`  |
| No timeout notifications  | Verify `fw_timeout_enabled` is `true` in `fw_module_settings`                                     |
| Executions not timing out | Verify `deadline_at` is set on executions and `timeout_config.enabled` on the workflow definition |
| Extension failing         | Verify user has `fw.workflows.admin` permission and execution is in `running`/`paused` status     |