# Runs, Retries & Failures (/concepts/runs-retries-failures)





A workflow describes a job. A run is one pass through that workflow, and each run has its own steps, status, and result in the agent's [Activity log](/concepts/logs-and-audit-trails). A run can handle one request or several, so when something goes wrong, check which request inside the run it affected.

<Callout title="Ask the right question">
  When something goes wrong, the useful question is not just "did it fail?" It
  is "which step failed, what already happened, and what needs to change before
  we try again?"
</Callout>

## Runs and steps [#runs-and-steps]

Say an agent handles email inquiries. Its workflow reads a message, checks a reference document, prepares a reply, asks a person to review it, and saves an approved draft.

The workflow is the same each time. The message and the answer are different. Each time the agent works through the workflow is a run, and each part of the job is a step.

Trelium's workflows include validation, an [Activity log](/concepts/logs-and-audit-trails), and exception handling. These help your team review the work rather than judge it only by whether a final result appeared.

## Where to see a run that went wrong [#where-to-see-a-run-that-went-wrong]

Open the agent's workspace and select **Activity log**. You can also open work from the Jobs board. Each row is one run and shows a status such as Running, Completed, or Cancelled, along with the apps it used and when it started. Other labels you may see on the Jobs board, such as Needs attention, group work for the team and are not the same list as run statuses. Open a run to see each step it took and when, which tells you how far it got. A business check that fails can still show completed steps (for example sending a review email) without the run being a technical failure. See [Logs & Audit Trails](/concepts/logs-and-audit-trails).

Work that needs a decision reaches a person as a review request, such as a message in Slack or an email. Which route is used is set with the workflow and the tools you connect. Settle with the Trelium team during setup who should hear about a run that stops for a technical reason, and how. Until that is in place, make checking the Activity log part of someone's routine.

<figure style="{ maxWidth: &#x22;36rem&#x22;, margin: &#x22;1.5rem auto&#x22; }">
    <img alt="One run opened in an agent's Activity log. Its status, Cancelled, is highlighted, with Gmail and Google Sheets icons, 147 credits used, a start time of 14:10, and a duration of 8 minutes 16 seconds. Below it, steps are listed newest first, each with a time and duration. The top step, Write Log Row, is highlighted as the last step the run reached, above steps such as Send Review Email, Extract Po From Text, Read Email Text, and Load Registers." src="__img0" />

  <figcaption style="{ fontSize: &#x22;0.875rem&#x22;, opacity: 0.8, marginTop: &#x22;0.5rem&#x22; }">
    A run that did not finish, opened in the Activity log. The status shows how it ended, and the steps are listed newest first, so the top one is the last step the run reached.
  </figcaption>
</figure>

## A failed step is not the same as a bad request [#a-failed-step-is-not-the-same-as-a-bad-request]

There are different reasons a job might not reach its finished state:

| Situation                                       | What needs attention                                                                                                          |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| A tool cannot be reached                        | Check the connection or whether the tool is available.                                                                        |
| The request is missing a detail                 | Get the missing information. Trying the same request again will not supply it.                                                |
| Two records disagree                            | Review the difference and decide which information to use.                                                                    |
| The agent cannot tell what a page is asking for | The run stops and surfaces as an exception. Your team looks at what happened. See [Browser Agents](/concepts/browser-agents). |
| The workflow needs approval                     | A person needs to make the decision. Waiting for that decision is not the same as a technical failure.                        |

Trelium routes exceptions and approval-sensitive work to people. A request that needs a decision should not be treated as a temporary connection problem. See [Validation & Exceptions](/concepts/validation-and-exceptions) for how checks decide what goes to a person.

## What a retry means [#what-a-retry-means]

A retry means trying work again after an unsuccessful attempt. It can help with a temporary problem, such as a tool being unavailable. It does not fix a missing detail, a conflicting record, or a decision that belongs to a person.

Before trying again, check whether the cause has changed. Also check what the first attempt already did. A run can have useful completed work before a later step fails.

Some temporary problems are retried automatically, such as a short file-transfer failure. Optional Auto-Healing can try to fix a failure and then run the job again from the start. That is different from a person opening a run and deciding what to do next. Exact retry counts, delays, and which failures qualify are set with the product; do not assume a universal policy from these docs.

There is no single guaranteed outcome after every failure. A business exception follows the branches in your workflow. A run can wait on a person for credentials or approval. An unsupported browser challenge can stop the run. Notification settings can email your team when a job starts, finishes, is cancelled, or fails; settle during setup who should get those notices.

<Callout title="Check before repeating a change" type="warn">
  If an attempt may already have sent a message or changed a record, check the
  destination before trying again. A missing confirmation is not proof that
  nothing happened. Some recoveries, such as continuing after a browser sign-in,
  are built not to repeat work that may already have been sent. Other
  protections are business rules in the workflow, such as checking that a PO
  number was not entered before. None of that is a promise of exactly-once
  behavior for every connector.
</Callout>

## Reviewing failed work [#reviewing-failed-work]

The Activity log shows what a run did and where it stopped. To review a failure, work through it in order:

<Steps>
  <Step>
    ### Start with the request [#start-with-the-request]

    Find the request the run was handling. Everything else is easier to judge once you know what the job was.
  </Step>

  <Step>
    ### Find the step that could not finish [#find-the-step-that-could-not-finish]

    Identify where the run stopped, and what it had already done before that point.
  </Step>

  <Step>
    ### Check earlier changes [#check-earlier-changes]

    Look at the destination systems for anything the run already sent or saved, so nothing is done twice.
  </Step>

  <Step>
    ### Decide what kind of fix it needs [#decide-what-kind-of-fix-it-needs]

    It may be a connection repair, a corrected input, or a decision from a person. Only then try the work again.
  </Step>
</Steps>

If you are not sure how a particular failure should be handled, ask the Trelium team during setup or when it happens.

## Example: a reply that could not be saved [#example-a-reply-that-could-not-be-saved]

Here is how that review works in practice. This is an illustration, not a description of an automatic retry policy.

<Steps>
  <Step>
    ### The reply is prepared [#the-reply-is-prepared]

    An inquiry arrives by email. The agent checks the reference document and prepares a reply.
  </Step>

  <Step>
    ### A person approves it [#a-person-approves-it]

    A reviewer approves the reply.
  </Step>

  <Step>
    ### The save fails [#the-save-fails]

    The email tool is unavailable when the workflow tries to save the draft.
  </Step>

  <Step>
    ### The team checks first [#the-team-checks-first]

    Your team checks whether the draft was created despite the error. If it exists, they do not create another one. If it does not, they address the connection problem before trying the unfinished work again.
  </Step>

  <Step>
    ### The result is confirmed [#the-result-is-confirmed]

    After the next attempt, they check that the draft contains the approved reply.
  </Step>
</Steps>

The important distinction is between the work that was already reviewed and the step that could not finish. Repeating the whole job without checking could create a second draft or repeat an action that already succeeded.

## Where to go next [#where-to-go-next]

<Cards>
  <Card title="Validation & Exceptions" href="/concepts/validation-and-exceptions">
    How checks separate routine work from requests that need attention.
  </Card>

  <Card title="Human in the Loop" href="/concepts/human-in-the-loop">
    Where a person reviews or approves the work.
  </Card>

  <Card title="Browser Agents" href="/concepts/browser-agents">
    What happens when an agent cannot make sense of a page.
  </Card>

  <Card title="Connecting Systems" href="/concepts/connecting-systems">
    How access to your tools affects what an agent can do.
  </Card>
</Cards>
