Encore OS — Documentation

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:

Open the execution detail dialog
Click the Extend button next to the deadline indicator
Enter the extension duration (1–1440 minutes) and a reason (minimum 5 characters)
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:

Timeout Warning — Sent once when an execution reaches the warning threshold
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:

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

Guides

Form Builder

Workflow Builder

Wizards

Approvals

Automations & Rules

Execution & Runtime

Analytics & Audit

Execution Timeout Administration Guide

Overview

Configuration

Global Settings (FW Settings Page)

Per-Workflow Settings (Workflow Editor)

Timeout Behaviors

Deadline Extension

Monitoring

Execution Detail View

Notifications (PF-10)

pg_cron Setup

Troubleshooting

​Overview

​Configuration

​Global Settings (FW Settings Page)

​Per-Workflow Settings (Workflow Editor)

​Timeout Behaviors

​Deadline Extension

​Monitoring

​Execution Detail View

​Notifications (PF-10)

​pg_cron Setup

​Troubleshooting

Overview

Configuration

Global Settings (FW Settings Page)

Per-Workflow Settings (Workflow Editor)

Timeout Behaviors

Deadline Extension

Monitoring

Execution Detail View

Notifications (PF-10)

pg_cron Setup

Troubleshooting