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

# Workflow Start Failed

> The API persisted the agent_runs row but failed to start the Temporal workflow.

**HTTP status:** 500

## When this error occurs

`POST /agents/conversations/{id}/runs` succeeded in writing the `agent_runs` row, but
`WorkflowClient.start` raised before the Temporal frontend acknowledged the workflow execution.
Common causes (visible only in the server log):

* Temporal frontend is unreachable (network partition, deploy-in-flight).
* The workflow id `agent_run_<uuid>` collides with an existing execution (very rare;
  effectively impossible given the UUID).
* The Temporal namespace doesn't exist or the worker isn't connected to it.

The row remains in `pending` status. The cleanup activity will eventually flip it to `failed`
via a heartbeat / supervisor mechanism, or operators can re-attempt the workflow start manually.

## How to fix

This is a transient platform error. Retry the same request with the **same `client_op_id`** —
the idempotency guarantee returns the existing `agent_runs` row (still `pending` or possibly
already `running` if the workflow eventually did start). If the underlying Temporal outage has
resolved, the workflow start will succeed on retry.