Understand the structure of Cotonity's workflow error logs, learn to pinpoint which step is failing, and follow a systematic approach to fix step-level errors.
Locating the error in the activity log
Every workflow run produces a structured execution record accessible from the agent's Activity tab. Each record shows the run start time, final status (Completed, Failed, or Timed Out), and a collapsible step-by-step trace. Expand the trace to see which step emitted the error. Steps are listed in execution order; the first step marked with a red error icon is the one that caused the run to abort. Click the step row to expand the error detail panel, which displays the error code, a human-readable message, and the input payload the step received — all three are essential for diagnosing the root cause.
Understanding error codes
Cotonity uses a hierarchical error code system. Codes beginning with 4xx indicate a configuration problem that you can fix — for example, 400 means a required field was empty, and 422 means a value failed validation. Codes beginning with 5xx indicate a transient server or upstream error that may resolve on retry. The error detail panel includes a 'View documentation' link that opens the relevant reference article for each code. If the error message references a variable name such as `{{contact.email}}`, the issue is that the variable resolved to null; verify the upstream step that sets this property actually ran successfully.
Reproducing and isolating the failure
Use the 'Re-run from step' feature to replay a failed run starting from the failing step, using the same input data recorded during the original execution. This isolates the problem to that step without re-triggering earlier actions that may have already produced side effects such as sending an email or creating a record. If the step succeeds during the replay but failed originally, the issue is likely a transient upstream error. If it fails again with the same error, the problem is deterministic and you should focus on the step's configuration, its input mapping, or the validity of any credentials it uses.
Common step failure patterns
The three most common step failures across Cotonity customers are: (1) Missing required field — a downstream step expects a value that an upstream step did not produce, usually because an earlier conditional branch was skipped. Fix this by adding a default value or a null-check condition before the failing step. (2) Credential expired — the step uses an OAuth connection whose access token has expired; go to Settings > Connections and reconnect the affected app. (3) Schema mismatch — the step sends data to an external API, but the payload structure changed after the workflow was built. Re-open the step editor and remap the fields to match the current API schema.