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

# Troubleshooting

> Diagnose and fix issues when an agent doesn't behave as expected

This page helps you diagnose and fix issues when an agent doesn't behave as expected — whether it fails with an error or completes with the wrong output.

## 1) Start With the Fast Path: Inspect the Last Run

The quickest way to debug is to look at the most recent execution.

In Twin, your first stop should always be:

* The **latest run details** (what the agent did, step by step)
* The **inputs** that were provided
* Any **errors / warnings** surfaced during execution

If you're using the chat editor, describe what happened and reference the last run so Twin can reason over it.

<Card title="Examples of what to ask in chat" icon="message" color="#F4D03F">
  * "This agent run failed — explain what happened and how to fix it."
  * "The run completed but the output is wrong. Identify where it went off track."
  * "Rerun with the same input, but add stronger extraction rules and return structured output."
</Card>

## 2) If the Agent Finished but the Output Is Wrong

Sometimes everything "succeeds," but the result is incomplete, oddly formatted, or inaccurate. Treat this differently than a hard failure.

### Debug checklist

<AccordionGroup>
  <Accordion title="Validate inputs" icon="input-pipe" color="#F4D03F">
    * Were you using the expected URL, file, row, or payload?
    * Are fields missing or in a different format than usual?
  </Accordion>

  <Accordion title="Follow the execution path" icon="route" color="#F4D03F">
    * Review the run steps and confirm the agent visited the right page(s) and captured the right data.
    * Look for skipped branches (filters, conditions, early exits).
  </Accordion>

  <Accordion title="Reduce the problem" icon="minimize" color="#F4D03F">
    Re-run with a very simple input you can predict:

    * Example: use one test URL instead of a list of 50
    * Example: use a single row instead of the full spreadsheet

    If the simple case works, the issue is likely input complexity or edge cases.
  </Accordion>

  <Accordion title="Check decision points" icon="code-branch" color="#F4D03F">
    If the agent is making choices (e.g., "pick the best result", "find the right page"), tighten your instructions:

    * Specify which page to prefer (About vs Team vs Contact)
    * Define what counts as a "match"
    * Define the exact output schema
  </Accordion>

  <Accordion title="Verify external systems" icon="plug" color="#F4D03F">
    If the agent writes into a tool (Sheets, CRM, email), confirm:

    * Correct destination
    * Correct permissions
    * Correct field mapping
  </Accordion>
</AccordionGroup>

## 3) Common Failure Patterns

These are the most frequent reasons an agent fails or becomes unreliable:

<CardGroup cols={3}>
  <Card title="Web Access & Page Changes" icon="globe" color="#F4D03F">
    * The page layout changed
    * Content loads dynamically and needs extra waiting
    * The site blocks automation or rate-limits requests
  </Card>

  <Card title="Authentication Issues" icon="lock" color="#F4D03F">
    * The agent is being redirected to a login page
    * A session expired
    * Multi-factor authentication is required
  </Card>

  <Card title="Data & Formatting Issues" icon="file-excel" color="#F4D03F">
    * Input fields are empty or malformed
    * Outputs are in a different format than expected
    * A filter is too strict (or not strict enough)
  </Card>

  <Card title="Retry Loops & Excessive Credits" icon="rotate" color="#F4D03F">
    * The agent retries a failed step repeatedly (e.g., sandbox or permission errors)
    * Expensive tools are chosen when simpler alternatives exist
    * Long-running agents accumulate context, increasing cost per step
  </Card>

  <Card title="Agent Ignoring Instructions" icon="triangle-exclamation" color="#F4D03F">
    * Complex goals with conflicting constraints confuse priority
    * The agent falls back to a prohibited tool when preferred methods fail
    * Step limits or explicit prohibitions aren't consistently tracked
  </Card>
</CardGroup>

## 4) Escalate to Support With the Right Details

If you've tried the steps above and you're still blocked, reach out — but include enough information for a fast diagnosis.

### Where to escalate

Twin has **live in-app support** with real human agents from the team, responding in under 20 minutes. Open [Twin](https://builder.twin.so/) and use the support chat — it's the fastest way to get help.

### What to include

| Item                   | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| **Agent link**         | Agent or workflow link (or the agent name in your workspace) |
| **Run ID**             | The exact failing run identifier                             |
| **Summary**            | One-line summary of the issue                                |
| **Expected vs actual** | What should have happened vs what did happen                 |
| **Inputs used**        | Redact sensitive info if needed                              |
| **What you tried**     | So support doesn't repeat steps                              |

## Quick Rule of Thumb

<CardGroup cols={3}>
  <Card title="Hard error / crash" icon="triangle-exclamation" color="#F4D03F">
    Focus on logs, permissions, authentication, and missing inputs
  </Card>

  <Card title="Success but wrong output" icon="circle-check" color="#F4D03F">
    Focus on data flow, decision rules, and tightening instructions
  </Card>

  <Card title="Intermittent failures" icon="rotate" color="#F4D03F">
    Focus on website variability, rate limits, and retries
  </Card>
</CardGroup>

## Getting Help

<CardGroup cols={2}>
  <Card title="Book a Call" icon="phone" href="https://calendly.com/d/cs9s-xbz-bv5/twin-feedback-call" color="#F4D03F">
    Talk to the founding team
  </Card>
</CardGroup>

## Still Stuck?

Contact us at **[hugo@twin.so](mailto:hugo@twin.so)** for urgent issues.