Exception management

When a validation or transform fails, you choose whether the run records a normal audit error or a durable exception you can triage later. Exceptions are distinct from canvas audit Warnings and Errors: they persist on the workflow and appear on Exception Management (?view=exceptions).

On error configuration

On an operation badge (and on node execution settings) you set On error:

raise error - existing audit error path for the run
raise exception - writes an audit row with reserved type exception, then the workflow engine syncs that row into Exception Management when the run finishes

You also set exception type (label), message, and severity. Severity is a text field: a level from 1 to 5, or a template that uses a column on the failing row. You can add other exception fields, such as status and assignee, the same way. Those values are stored when the exception is first created. The info icon beside each added field explains an example that uses this operation’s columns. The default exception type for an operation is {action} {type} issue (for example arrayLengthLessThan validation issue). For a node without an operation context, the default is {nodeType} issue.

Exception Management views

Open Exception Management from the workspace sidebar. Hover Exception Management or a named view under any workflow in the Workspaces explorer and choose the star to pin it for everyone in the workspace. That pin opens that workflow’s Exceptions. The tab stays in the header on every Workspaces pane. That header is favourite tabs only. The page you are viewing stays in that header as the active tab, and the star on that tab pins it for the workspace. Opening Exceptions underlines this pin, not the workflow file, even when both are starred. Double-click a pinned tab to set a display name for everyone in the workspace. When you open the workflow as a file, More file views includes Exceptions. When the workflow has tickets, Exceptions sits on the file-view strip with an amber count of those tickets. The count matches the Exception Management total, and it shows 99+ above 99. Choosing Exceptions opens Exception Management for that workflow. The folder uses ?view=exceptions. Each named view (Table, Board, Timeline, and views you add) uses ?view=exceptions&exceptionViewId= plus that view’s id, so you can bookmark or favourite a specific layout. The page shares one explorer: title, stats tiles, view tabs, and the table, board, or timeline body. Named views live on the workflow: table, board, list, calendar, timeline, JSON, Details, and Chart. You can create, rename, duplicate, reorder, and delete views. Each view has its own layout, which properties it shows, and its own filter, sort, and group. Each view also has a header: a title, a short description, and optional status tiles. You edit those under Header in view settings, and you can hide the header. View changes save with the workflow as you make them. Use the sliders control on the toolbar for view settings (layout, property visibility, filter, sort, conditional formatting, group, and header) and Exception Management property schema in one menu. In All Properties, a date or number has a format control. A date takes the patterns you accept and the pattern you show. A number format names the preset and shows its pattern: General (1300), Number, 2 decimals (1,300.00), Number, 1 decimal (1,300.0), Integer (1,300), Percent, 2 decimals (0.00%), Percent, 1 decimal (0.0%), Whole percent (0%), or Scientific (1.30E+03). The format you choose stays on that property. Conditional formatting is one sentence in view settings: if a property matches, or always, make the cell or the row a background, an underline, a left border, a colour dot, or an icon. The first matching rule of each style is the one you see. Drag a rule to change which match wins. An example cell at the bottom shows the rule you are hovering. In Property visibility, drag a property by its grip, type icon, or name to reorder columns for that view. Hide stays a separate control. When a list in view settings has more than ten items, a filter appears at the top of that list. Your last-selected tab is personal to you; it is not shared with the team.

On a node’s Explore tab, a bottom pane starts as a tab strip along the bottom of the editor. Exceptions stays idle until you open it. A count on the tab shows how many tickets that pane will list. When the count is zero, the collapsed tab is faded. Click the tab to open the list, and click it again to close it. Drag the tab up or down to resize the list. The view toolbar sits on the right of the tab. Select a data cell and the pane shows the tickets for that row. View settings on that pane include Upstream exceptions. It starts on, so the pane also lists tickets from the nodes and rows that produced the selected rows; turn it off to see this node’s tickets only. A cell whose data traces back to the column an earlier node flagged shows a hollow orange ring in the same mark as this node’s own exception; a ticket raised on the whole row marks every cell of that row. A filled orange dot is still this node’s exception, and it stays when the row has both. Hover the ring to read the ticket: its severity and message, the node and operation that raised it, the upstream row and column, and its status. With no row selected, that option covers every row of the port. The choice stays on the open editor. It is not saved with the view. The tab strip then reads how many exceptions that selection lists, with the selected-row count in a pill. The AI chat composer shows that row and that column with the node and the port. Remove the Row chip or the Cell chip to list every ticket for the node again. Column, filter, and sort changes on that pane are shared across nodes on the workflow. That pane’s view stays off the Exception Management tab, the sidebar, dashboards, and analysis view names.

The Exceptions view icon shows a count pill for active open exceptions and uses the colour of the worst open severity. That wash and count stay visible while Exception Management is the selected view. Severity colour comes from ticket levels 1-5. The pill shows 9+ when more than nine tickets are open.

Table

The default table is one row per ticket. Columns follow that view’s shown properties. You can wrap cells, freeze leading columns, resize data columns (including Status, Assignee, and Severity), and edit writable properties inline. The Inactive column shows a broken-link mark when a ticket has no matching row in the loaded data, and the agent’s face on that row. Hide it in view settings under Layout, in the Table section, with Inactive column. Board, list, and timeline still show that mark on the row. Select and Actions stay a fixed width. The footer downloads the rows loaded in that view as CSV or JSON. CSV uses the labels in the grid. JSON matches the JSON view, with each row id and the stored values. The file includes the shown data columns. Use the leading Select checkbox to pick rows on the current page. When two or more rows are selected, a compact Selection strip appears on the view toolbar with a Bulk Edit menu (aggregate property fields and per-bucket moves), configurable quick action chips, and a clear control. Actions include View (opens the Exception panel), Resolve, and Close.

Board

A board groups cards by a status, select, or people property. Drag a card between columns to update that property on the ticket. If the view has no group property yet, the board asks you to pick one. Column headers can add, rename, recolour, and reorder options for status and select properties.

List

A list is a compact vertical list: title plus shown properties. You can optionally group rows; group headers collapse.

Calendar and timeline

A calendar places tickets on a month grid by a date property you choose (Calendar by). Days without a date go to an Unscheduled tray. A timeline places a bar from a start date to an optional end date (Timeline by), with day, week, and month zoom. If the date binding is missing, the view opens and asks you to pick the date property.

JSON and Details

JSON shows the loaded page of tickets as read-only text. Details shows a row list beside a full page for the selected ticket: its properties and its history. Property visibility controls which fields appear on each row. All Properties controls which fields appear on the detail page.

Chart

A chart counts or sums the tickets in the view by one property: status, assignee, severity, type, a date, or any custom property. Pick vertical or horizontal bars, a line, a donut, or a single number. A date property buckets by day, week, month, or year. Group by adds a series breakdown on bars and lines. The chart respects the view’s filter, labels select, status, and people values by name, and updates as tickets change.

Exception panel

On Exception Management the workflow right toolbar shows Triggers, Audit log, and Developer Tools. Overview, Nodes, and Operations stay off that rail. Exception and AI Chat stay off the rail on every view. An open toolbar pushes the workflow header. Header AI Chat (sparkles) opens in its own column. On a wide workspace view, pin AI Chat to keep that column beside an open tool panel. The pin appears in the AI Chat header when the view has room for both panels. The pin starts off: opening AI Chat closes the open tool panel, and opening a tool panel closes AI Chat. Until you resize AI Chat, it matches the tools sidebar width. Home, Knowledge Graph, and Admin Header AI stay a single dock.

In the table, click Message, Type, or another surface cell (not Status, Assignee, or Severity) to select that ticket. The Exception panel opens when auto-open is on (the default). With auto-open off, the selection stays and the panel stays closed. Tick the row checkbox the same way. Two or more checkboxes switch the panel to bulk mode with a count in the header. Status, Assignee, and Severity stay dropdowns so you can change those fields without opening the dock.

On board, list, calendar, or timeline, click a card, row, chip, or bar to select the ticket. The Exception panel opens when auto-open is on. With auto-open off, the click selects the ticket and leaves the panel closed. View in Actions still opens it. The header control uses a sidebar icon. Its tooltip states whether auto-open is on, what a selection does, and what a click will do.

For one ticket, the panel shows schema-visible properties (system, origin, and custom) in schema order, excluding rows you mark default hidden in All Properties, plus Comments (append-only GitHub Flavored Markdown via Add comment; History renders that source) and History (status, severity, assignee, comments, and agent email). An agent that emails about the ticket names that ticket on the send. History adds an Email sent row for that ticket, and the reply adds an Email received row on the same ticket and continues the agent’s chat thread. Both rows show the mail itself: subject, sender or recipients (never Bcc), and the plain-text body, with Expand email on a long message. See Agent email. Comment rows show the commenter on the timeline (user, agent, or agent with a user badge). Captions read Comment added by the operator, or Comment added by the agent on behalf of the operator. Use Collapse and Expand on the History heading to switch compact density. Each History change is also recorded in the Activity log. Quick actions in the panel header come from Exception Management settings (defaults include Resolve and Close) plus Show on canvas.

For multiple tickets, Properties show aggregate rows: a count pill beside each value (always the number of selected tickets with that value, never ALL). Click a value to facet-filter the other properties. You can select more than one value in the same property. Values that no longer match stay visible at count 0, greyed out, and not clickable. Header quick actions run the same presets with an all suffix (for example Resolve all), skipping tickets where that action is disabled. Bulk property editing for checkbox selection also lives in the view-toolbar Bulk Edit menu; the panel does not show History in bulk mode. The bulk editor ends with Delete beside Apply. Delete asks you to confirm, then removes the selected exceptions and their comments. A later workflow run can raise those exceptions again. The activity log records each permanent delete.

Message is the raised exception text; it does not change when you add a comment. Enable the read-only Last comment system property in view settings when you want the newest comment body in table, board, or filters. Lineage stays on canvas Overview.

Resolve and Close update the ticket’s status option (defaults include Raised, Investigating, Awaiting review, Resolved, Closed, plus options you add in Exception Management settings). Assignee is a member of the workflow team (or the owner on a personal workflow). Unassigned cells show a dash. Assignment is stored on the ticket and survives reload. If that person later leaves the team, the cell still shows their name; the picker lists current members plus Unassigned only.

Properties and origin rows

Exception Management settings manage typed properties (text, number, select, status, date, people, checkbox, url, email). System fields (message, status, assignee, severity, type, identity keys) stay first-class. Originating-row snapshot keys appear as origin properties you can type, show, and order.

Columns that come from a ticket’s stored originating-row snapshot keep a Status-coloured left accent on the raising field. Presence (active / inactive) is machine-owned. Status is yours.

When the first Schema on a lineage defines a row identity key, live runs match the same ticket by that key:

A new key inserts a ticket.
A key still raising this run updates the snapshot and leaves the Status you set.
A key missing from this run’s exception set becomes inactive. It stays in its Status with a broken-link mark. Hover the mark to see that the exception has no matching row in the currently loaded data. Resolved plus inactive stays in Resolved.
If that key raises again, the same ticket becomes active and keeps your Status.

The first run after you define a Schema key does not rematch older tickets that used a full-row content hash; those become inactive and current-run exceptions insert as new tickets.

Open Exception Ticket Persistence from the Workspaces explorer (Community chip, Financial) to walk this loop on a five-row trade blotter keyed by tradeId. Quantity and notional validations raise exceptions. You can Resolve a ticket, edit or delete that trade in Static Data, and re-run to see the same ticket stay, become inactive, or reactivate with the Status you set.

Exceptions in Analysis documents and dashboards

Analysis documents, and dashboard Markdown and Stat blocks, render Jinja templates against live workflow data. Alongside nodes and byTitle, a template can read this workflow’s exceptions through exceptions.

Expression	What it returns
`exceptions.rows`	Every exception on the workflow.
`exceptions.views["Table"].rows`	The rows of that named view, after the view’s filter and sort order.
`exceptions.viewNames`	The names of your Exception Management views.

Each row carries message, type, status (the option id), statusName (the label you see in the table), open, severityLevel, nodeId, nodeTitle, assigneeName, createdAt, lastSeenAt, and lastCommentBody. source holds the originating row keyed by column, and properties holds your custom properties keyed by property name. Select, status, multi-select, and people properties read as their labels.

Count exceptions in a sentence or a Stat block:

{{ exceptions.rows | selectattr("open") | list | length }} open of {{ exceptions.rows | length }}

Render a view as a table. Keep the for and endfor tags on their own lines so each exception becomes one table row:

| Node | Message | Status | Severity | Assignee |
| --- | --- | --- | --- | --- |
{% for r in exceptions.views["Table"].rows -%}
| {{ r.nodeTitle }} | {{ r.message | replace("|", "\\|") }} | {{ r.statusName }} | {{ r.severityLevel }} | {{ r.assigneeName or "Unassigned" }} |
{% endfor %}

Add a column from the originating row with r.source["tradeId"], or from a custom property with r.properties["Team"].

The editor suggests exceptions, its members, and your view names as you type. A view name that matches no view, or more than one view, shows an inline template error at that spot and the rest of the document still renders. Give each view a distinct name to reference it. PDF, DOCX, and XLSX downloads render the same template.

Agent tools

When you assign the Workflow capability on an agent, that agent can list, read, and update Exception Management tickets, and can change that workflow’s Exception Management properties and views. Pass the Convex workflowId from chat User context JSON. Access follows workflow read and write permission; these tools are not gated by data-query or workflow-config chat flags.

When an agent schedule fires on exception_raised or exception_status_changed, User context includes selection.exceptionIds and exception.exceptions for every ticket in that batch. A run that raises many tickets starts one turn.

When you select one or more tickets in Exception Management (open ticket or table checkboxes), new AI chats on that workflow also receive selection.exceptionIds. The AI Chat composer shows a chip with each ticket’s message (not the document id). Hover the chip for Chat context: plus the kind and full message. Use workflow_getException with each id.

Tool	What the agent can do
`workflow_listExceptions`	Bounded summaries (default 25 tickets, maximum 100) with optional filters for status, node, type, and severity. Each row includes the status option id and display name. The list does not return originating-row snapshots.
`workflow_getException`	One ticket, property values (the Actions column is table chrome and is omitted), append-only comments, history, and the workflow’s status options. Pass both `workflowId` and `exceptionId`. A mismatch or missing read access returns empty.
`workflow_updateException`	Writable ticket fields: status option (id or name), severity 1-5, assignee (Convex user id or null), custom properties, and an optional append-only comment. Unknown statuses are rejected with the available options. Only this ticket changes.
`workflow_getExceptionManagement`	The workflow’s Exception Management properties, named views, and assignee pool. Use this before you change setup.
`workflow_updateExceptionManagement`	Ordered edits to properties and views (add, rename, retype, delete, reorder, configure show/filter/sort/groupBy). You cannot delete system properties or the last view.

See Tools and MCP for how you assign built-in tools.

Activity log - exception changes alongside every other tracked change, with the same views
Workflow orchestration - pipeline model and execution engine
Operation node - transforms and validations on rows
Schema node - row identity key that Exception Management uses to match tickets across runs
Tools and MCP - built-in workflow_* exception tools on the Workflow capability tile