Investigate why a Cotonity agent terminates before reaching its final step, covering timeout limits, memory constraints, infinite loops, and unhandled error conditions.
Reading the termination reason
When an agent stops mid-run, the Activity log will show a run record with a status of 'Failed', 'Timed Out', or 'Stopped'. Click the run to open the execution trace and scroll to the last step that executed successfully — the step immediately after it is where execution halted. The run summary panel on the right shows a 'Termination reason' field that provides a machine-readable code: TIMEOUT means the run exceeded its time limit, MEMORY_LIMIT means the run exceeded its memory allocation, ERROR_UNHANDLED means a step threw an error that was not caught by an error handler, and STOPPED_BY_USER means the run was manually terminated from the dashboard.
Resolving timeout errors
Each Cotonity plan has a maximum run duration. If your workflow needs to process large volumes of data or call slow external services, you may hit this limit. To check your current limit, navigate to Settings > Plan. Common solutions include: breaking a long-running workflow into smaller sub-workflows triggered in sequence, enabling pagination on data-fetch steps to process records in smaller batches across multiple runs, and optimizing slow API calls as described in the performance tips article. If none of these options are feasible, contact support to discuss whether an extended timeout limit is available on your plan.
Diagnosing infinite or very long loops
A loop step that iterates over an unexpectedly large dataset is a frequent cause of timeout errors. In the execution trace, expand the loop step to see how many iterations it completed before the run was terminated. If the iteration count is much higher than expected, examine the input data for the loop: there may be a filter step upstream that is not correctly reducing the dataset size, or the loop may be processing a list that grows unbounded over time. Add an explicit list size check before the loop using a conditional step, and if the list exceeds a safe threshold, either process a subset or split the work across multiple runs using an offset-based pagination pattern.
Adding error handlers to prevent mid-run stops
An unhandled error in any step will cause the entire run to abort by default. To make your workflow more resilient, add error handler branches to steps that are likely to fail transiently — such as HTTP request steps that call external APIs. Select the step, open its settings panel, and enable 'Error handling'. You can configure the step to retry on failure (with configurable retry count and delay), to continue to the next step with a default value, or to branch to a dedicated error-handling sub-workflow that logs the failure and sends an alert. Using error handlers prevents a single transient failure from stopping an otherwise healthy workflow.