# How to Create Exception Lanes in Archify Workflow Diagrams

> Learn how to create exception lanes in Archify workflow diagrams by defining lanes with a variant exception and connecting error-handling nodes with error roles. Simplify your workflow visualization.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-12

---

**To create exception lanes in Archify workflow diagrams, define a lane with `"variant": "exception"` in the lanes array, place error-handling nodes in that lane, and connect them with edges marked `"role": "error"`.**

Archify is an open-source diagramming framework that supports structured workflow visualization through JSON-based schemas. Creating **exception lanes in Archify workflow diagrams** allows you to visually separate error-handling paths from primary execution flows, making complex system architectures more readable and maintainable.

## Understanding the Schema Definitions

In the Archify workflow schema, exception lanes are defined as a specific lane variant, while error edges represent a distinct edge role. According to the [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) file, the lanes definition supports a `variant` property that accepts either `"normal"` or `"exception"` values. Similarly, the edge role enum includes `"error"` as a valid option for denoting failure paths.

## Step 1: Define the Exception Lane

To implement an exception lane, modify the `lanes` array in your workflow JSON file. In [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 63-86), the schema defines lane objects with a `variant` property. Set this to `"exception"` to designate the lane as an error-handling path:

```json
{
  "lanes": [
    { "id": "main", "label": "Main Flow" },
    { "id": "exceptions", "label": "Exception Handling", "variant": "exception" }
  ]
}

```

Exception lanes receive distinct visual styling—typically a red background or other theme-defined cues—to differentiate them from normal lanes.

## Step 2: Assign Nodes to the Exception Lane

Place error-handling nodes—such as "Blocked" or "Retry" states—inside the exception lane by setting their `lane` property to match the exception lane's `id`. This pattern appears in [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json):

```json
{
  "nodes": [
    { "id": "blocked", "lane": "exceptions", "col": 4, "type": "security", "label": "Blocked" },
    { "id": "retry", "lane": "exceptions", "col": 5, "type": "messagebus", "label": "Retry Path" }
  ]
}

```

This placement ensures the renderer positions these nodes within the exception lane's visual boundaries.

## Step 3: Mark Error Edges

Define error edges in the `edges` array by setting `"role": "error"`. The schema defines this role in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 60-63) as part of the edge role enum. Error edges typically route from normal lane nodes to exception lane nodes:

```json
{
  "from": "approval",
  "to": "blocked",
  "label": "denied",
  "variant": "security",
  "role": "error",
  "fromSide": "bottom",
  "toSide": "top",
  "route": "drop"
}

```

These edges render with visual distinctions—such as red arrows—to indicate failure paths.

## Complete Working Example

Here is a complete, runnable workflow JSON demonstrating an exception lane and error edge configuration:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Simple Exception Demo", "viewBox": [720, 900] },
  "lanes": [
    { "id": "main", "label": "Main Flow" },
    { "id": "error", "label": "Error Path", "variant": "exception" }
  ],
  "nodes": [
    { "id": "start", "lane": "main", "col": 0, "type": "frontend", "label": "Start" },
    { "id": "process", "lane": "main", "col": 1, "type": "backend", "label": "Process" },
    { "id": "fail", "lane": "error", "col": 1, "type": "security", "label": "Failed" }
  ],
  "edges": [
    { "from": "start", "to": "process", "variant": "default" },
    { "from": "process", "to": "fail", "role": "error", "variant": "security" }
  ]
}

```

This example follows the schema rules defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and mirrors patterns found in [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json).

## Schema Validation and Best Practices

The Archify renderer validates workflow diagrams against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json). When using exception lanes, ensure:

- The lane `id` referenced in node `lane` properties exists in the `lanes` array
- The `variant` value is exactly `"exception"` (case-sensitive)
- Error edges use the exact string `"error"` for the `role` property

Separating error paths into distinct lanes improves diagram readability by making failure routes explicit and visually distinct from the primary execution flow.

## Summary

- **Exception lanes** are created by setting `"variant": "exception"` in lane objects within [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)
- **Error edges** are defined by setting `"role": "error"` in edge objects, as specified in lines 60-63 of the schema
- Nodes are assigned to exception lanes via the `lane` property referencing the lane's `id`
- The renderer applies distinct visual styling (red backgrounds/arrows) to exception lanes and error edges
- Reference implementation exists in [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json)

## Frequently Asked Questions

### Can a workflow have multiple exception lanes?

Yes. The schema allows multiple lanes with `"variant": "exception"`. You can organize different error types into separate exception lanes (e.g., validation errors vs. security errors) by defining multiple lanes with unique IDs and assigning relevant nodes to each.

### What visual differences apply to error edges?

Error edges marked with `"role": "error"` typically render with red-colored arrows or other theme-defined visual cues. The specific styling depends on the Archify theme configuration, but the schema ensures these edges are semantically distinct from standard flow edges.

### Do exception lanes require special node types?

No. Exception lanes can contain any valid node type defined in the schema. However, common conventions include using `"type": "security"` for blocked operations or `"type": "messagebus"` for retry mechanisms, as seen in the agent-tool-call example.

### Where is the exception lane schema defined?

The lane variant schema is defined in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) at lines 63-86, which specifies the `variant` enum containing `"normal"` and `"exception"`. The edge role schema is defined at lines 60-63, which includes `"error"` in the allowed roles.