Skip to main content

​
Exception Types

Nen defines three exception types:
ExceptionDescription
WorkflowErrorBase exception for all workflow failures
RPCErrorCommunication failure with the orchestrator
TimeoutErrorOperation exceeded its timeout
from nen import WorkflowError

​
Catching Errors

If you want to handle failures gracefully such as for retry or to provide a fallback, wrap calls in try/except.

​
Retry pattern

workflow.py
def run(params: Params) -> Result:
    agent = Agent()
    for attempt in range(3):
        try:
            agent.execute("Click Submit")
            break
        except WorkflowError:
            if attempt == 2:
                raise
            agent.execute("Scroll down to find the Submit button")

​
Conditional recovery

workflow.py
def run(params: Params) -> Result:
    agent = Agent()
    try:
        agent.execute("Click the Export button")
    except WorkflowError:
        # Try an alternative path
        agent.execute("Open the File menu and click Export")

​
Raising Errors

Raise any exception to signal a workflow failure. The exception message is sent to the error webhook.
workflow.py
def run(params: Params) -> Result:
    raise RuntimeError("Application failed to load")
workflow.py
def run(params: Params) -> Result:
    agent = Agent()
    if not agent.verify("Is the dashboard loaded?", timeout=30):
        raise RuntimeError("Dashboard did not load within 30 seconds")
workflow.py
def run(params: Params) -> Result:
    agent = Agent()
    data = agent.extract("Extract the order ID", OrderSchema.model_json_schema())
    if not data.get("order_id"):
        raise ValueError("No order ID found on the page")

​
Uncaught errors

If an exception propagates out of run() without being caught, the orchestrator treats the run as a hard failure. Use this intentionally when the workflow encounters a condition it cannot recover from — for example, a required file is missing, an external service is unreachable, or an assertion about the environment fails. The run is marked as failed and the exception message is surfaced to the caller, making the failure visible rather than silently returning a partial or incorrect result.
workflow.py
def run(params: Params) -> Result:
    if not some_precondition:
        raise RuntimeError("Precondition not met — aborting run")
    ...
Catch and handle errors internally only when your workflow can meaningfully recover. For unrecoverable conditions, let the exception propagate.

​
Error Webhooks

When a workflow fails, the error webhook payload contains the exception message: 
{
  "success": false,
  "error": "No images found for user 0123456789abcdef"
}
Any unhandled exception in your run() function automatically becomes an error webhook. You don’t need to catch and re-raise — just let it propagate.