|
| 1 | +--- |
| 2 | +title: "Runs & attempts" |
| 3 | +description: "Understanding the lifecycle of task execution in Trigger.dev" |
| 4 | +--- |
| 5 | + |
| 6 | +In Trigger.dev, the concepts of runs and attempts are fundamental to understanding how tasks are executed and managed. This article explains these concepts in detail and provides insights into the various states a run can go through during its lifecycle. |
| 7 | + |
| 8 | +## What are runs? |
| 9 | + |
| 10 | +A run is created when you trigger a task (e.g. calling `yourTask.trigger({ foo: "bar" })`). It represents a single instance of a task being executed and contains the following key information: |
| 11 | + |
| 12 | +- A unique run ID |
| 13 | +- The current status of the run |
| 14 | +- The payload (input data) for the task |
| 15 | +- Lots of other metadata |
| 16 | + |
| 17 | +## The run lifecycle |
| 18 | + |
| 19 | +A run can go through **various** states during its lifecycle. The following diagram illustrates a typical state transition where a single run is triggered and completes successfully: |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | +Runs can also find themselves in lots of other states depending on what's happening at any given time. The following sections describe all the possible states in more detail. |
| 24 | + |
| 25 | +### Initial States |
| 26 | + |
| 27 | +<Icon icon="rectangle-history" iconType="solid" color="#FBBF24" size={17} /> **Waiting for deploy**: If a task is triggered before it has been deployed, the run enters this state and waits for the task to be deployed. |
| 28 | + |
| 29 | +<Icon icon="clock" iconType="solid" color="#878C99" size={17} /> **Delayed**: When a run is triggered with a delay, it enters this state until the specified delay period has passed. |
| 30 | + |
| 31 | +<Icon icon="rectangle-history" iconType="solid" color="#878C99" size={17} /> **Queued**: The run is ready to be executed and is waiting in the queue. |
| 32 | + |
| 33 | +### Execution States |
| 34 | + |
| 35 | +<Icon icon="spinner-third" iconType="duotone" color="#3B82F6" size={17} /> **Executing**: The task is currently running. |
| 36 | + |
| 37 | +<Icon icon="arrows-rotate" iconType="solid" color="#3B82F6" size={17} /> **Reattempting**: The task has failed and is being retried. |
| 38 | + |
| 39 | +<Icon icon="snowflake" iconType="solid" color="#68BAF2" size={17} /> **Frozen**: Task has been frozen and is waiting to be resumed. |
| 40 | + |
| 41 | +### Final States |
| 42 | + |
| 43 | +<Icon icon="circle-check" iconType="solid" color="#28BF5C" size={17} /> **Completed**: The task has successfully finished execution. |
| 44 | + |
| 45 | +<Icon icon="ban" iconType="solid" color="#878C99" size={17} /> **Canceled**: The run was manually canceled by the user. |
| 46 | + |
| 47 | +<Icon icon="circle-xmark" iconType="solid" color="#E11D48" size={17} /> **Failed**: The task has failed to complete successfully. |
| 48 | + |
| 49 | +<Icon icon="alarm-exclamation" iconType="solid" color="#E11D48" size={17} /> **Timed out**: Task has failed because it exceeded its `maxDuration`. |
| 50 | + |
| 51 | +<Icon icon="fire" iconType="solid" color="#E11D48" size={17} /> **Crashed**: The worker process crashed during execution (likely due to an Out of Memory error). |
| 52 | + |
| 53 | +<Icon icon="bolt-slash" iconType="solid" color="#E11D48" size={17} /> **Interrupted**: In development mode, when the CLI is disconnected. |
| 54 | + |
| 55 | +<Icon icon="bug" iconType="solid" color="#E11D48" size={17} /> **System failure**: An unrecoverable system error has occurred. |
| 56 | + |
| 57 | +<Icon icon="trash-can" iconType="solid" color="#878C99" size={17} /> **Expired**: The run's Time-to-Live (TTL) has passed before it could start executing. |
| 58 | + |
| 59 | +## Attempts |
| 60 | + |
| 61 | +An attempt represents a single execution of a task within a run. A run can have one or more attempts, depending on the task's retry settings and whether it fails. Each attempt has: |
| 62 | + |
| 63 | +- A unique attempt ID |
| 64 | +- A status |
| 65 | +- An output (if successful) or an error (if failed) |
| 66 | + |
| 67 | +When a task fails, it will be retried according to its retry settings, creating new attempts until it either succeeds or reaches the retry limit. |
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | +## Run completion |
| 72 | + |
| 73 | +A run is considered finished when: |
| 74 | + |
| 75 | +1. The last attempt succeeds, or |
| 76 | +2. The task has reached its retry limit and all attempts have failed |
| 77 | + |
| 78 | +At this point, the run will have either an output (if successful) or an error (if failed). |
| 79 | + |
| 80 | +## Advanced run features |
| 81 | + |
| 82 | +### Idempotency Keys |
| 83 | + |
| 84 | +When triggering a task, you can provide an idempotency key to ensure the task is executed only once, even if triggered multiple times. This is useful for preventing duplicate executions in distributed systems. |
| 85 | + |
| 86 | +```javascript |
| 87 | +yourTask.trigger({ foo: "bar" }, { idempotencyKey: "unique-key" }); |
| 88 | +``` |
| 89 | + |
| 90 | +- If a run with the same idempotency key is already in progress, the new trigger will be ignored. |
| 91 | +- If the run has already finished, the previous output or error will be returned. |
| 92 | + |
| 93 | +### Canceling runs |
| 94 | + |
| 95 | +You can cancel an in-progress run using the API or the dashboard: |
| 96 | + |
| 97 | +```ts |
| 98 | +runs.cancel(runId); |
| 99 | +``` |
| 100 | + |
| 101 | +When a run is canceled: |
| 102 | + |
| 103 | +– The task execution is stopped |
| 104 | + |
| 105 | +– The run is marked as canceled |
| 106 | + |
| 107 | +– The task will not be retried |
| 108 | + |
| 109 | +– Any in-progress child runs are also canceled |
| 110 | + |
| 111 | +### Time-to-live (TTL) |
| 112 | + |
| 113 | +You can set a TTL when triggering a run: |
| 114 | + |
| 115 | +```ts |
| 116 | +yourTask.trigger({ foo: "bar" }, { ttl: "10m" }); |
| 117 | +``` |
| 118 | + |
| 119 | +If the run hasn't started within the specified TTL, it will automatically expire. This is useful for time-sensitive tasks. Note that dev runs automatically have a 10-minute TTL. |
| 120 | + |
| 121 | + |
| 122 | + |
| 123 | +### Delayed runs |
| 124 | + |
| 125 | +You can schedule a run to start after a specified delay: |
| 126 | + |
| 127 | +```ts |
| 128 | +yourTask.trigger({ foo: "bar" }, { delay: "1h" }); |
| 129 | +``` |
| 130 | + |
| 131 | +This is useful for tasks that need to be executed at a specific time in the future. |
| 132 | + |
| 133 | + |
| 134 | + |
| 135 | +### Replaying runs |
| 136 | + |
| 137 | +You can create a new run with the same payload as a previous run: |
| 138 | + |
| 139 | +```ts |
| 140 | +runs.replay(runId); |
| 141 | +``` |
| 142 | + |
| 143 | +This is useful for re-running a task with the same input, especially for debugging or recovering from failures. The new run will use the latest version of the task. |
| 144 | + |
| 145 | +You can also replay runs from the dashboard using the same or different payload. Learn how to do this [here](/replaying). |
| 146 | + |
| 147 | +### Waiting for runs |
| 148 | + |
| 149 | +#### triggerAndWait() |
| 150 | + |
| 151 | +The `triggerAndWait()` function triggers a task and then lets you wait for the result before continuing. [Learn more about triggerAndWait()](/triggering#yourtask-triggerandwait). |
| 152 | + |
| 153 | +.png) |
| 154 | + |
| 155 | +#### batchTriggerAndWait() |
| 156 | + |
| 157 | +Similar to `triggerAndWait()`, the `batchTriggerAndWait()` function lets you batch trigger a task and wait for all the results [Learn more about batchTriggerAndWait()](/triggering#yourtask-batchtriggerandwait). |
| 158 | + |
| 159 | +.png) |
| 160 | + |
| 161 | +### Runs API |
| 162 | + |
| 163 | +The runs API provides methods to interact with and manage runs: |
| 164 | + |
| 165 | +```ts |
| 166 | +// List all runs |
| 167 | +runs.list(); |
| 168 | + |
| 169 | +// Get a specific run by ID |
| 170 | +runs.retrieve(runId); |
| 171 | + |
| 172 | +// Replay a run |
| 173 | +runs.replay(runId); |
| 174 | + |
| 175 | +// Reschedule a run |
| 176 | +runs.reschedule(runId, delay); |
| 177 | + |
| 178 | +// Cancel a run |
| 179 | +runs.cancel(runId); |
| 180 | +``` |
| 181 | + |
| 182 | +These methods allow you to access detailed information about runs and their attempts, including payloads, outputs, parent runs, and child runs. |
| 183 | + |
| 184 | +### Triggering runs for undeployed tasks |
| 185 | + |
| 186 | +It's possible to trigger a run for a task that hasn't been deployed yet. The run will enter the "Waiting for deploy" state until the task is deployed. Once deployed, the run will be queued and executed normally. |
| 187 | +This feature is particularly useful in CI/CD pipelines where you want to trigger tasks before the deployment is complete. |
0 commit comments