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

# Troubleshooting

> Fixes for the most common issues: connections, approvals, and the NetSuite busy queue.

Most problems in Erstan come down to a missing connection, an authorization that needs renewing, or an agent that can't start. This page walks through the issues people hit most, with the fastest fix for each.

<Tip>
  Many issues fix themselves once the right connection is healthy. Check **Connectors** first — a status badge there usually points straight at the cause.
</Tip>

## Common issues

<AccordionGroup>
  <Accordion title="Chat says 'Connect an LLM to start chatting'" icon="message-square-off">
    Chat and agents need a connected AI model to run. When no [LLM provider](/connectors/llm-providers) is connected, the composer is disabled and reads **Connect an LLM to start chatting...** with a link to Connectors.

    <Steps>
      <Step title="Open Connectors">
        Go to **Connectors** in the workspace, or click the link in the composer message (it opens Connectors filtered to AI providers).
      </Step>

      <Step title="Connect a provider">
        Open **OpenAI** or **Anthropic**, go to the **Tokens** tab, paste your workspace **Provider API key**, and save.
      </Step>

      <Step title="Enable a model">
        On the **Models** tab, enable at least one model and save. That model becomes selectable in chat.
      </Step>
    </Steps>

    <Note>
      One workspace API key is stored per provider, and the available models are managed by your Erstan admin — you choose which of them to enable. Connecting a provider is an Owner/Admin action.
    </Note>
  </Accordion>

  <Accordion title="'NetSuite not connected' or a 'Connection required' banner" icon="plug-zap">
    If an agent or chat needs NetSuite and it isn't connected, you'll see a **Connection required** banner (amber) on the agent, or a prompt in chat. NetSuite connects in two stages.

    * **Owners and admins** set up the shared **Workspace OAuth connection** once (see [Connecting NetSuite](/connectors/netsuite)).
    * **Every member** then authorizes their own NetSuite user before agents can act as them (see [Authorizing your NetSuite user](/connectors/netsuite-authorize)).

    If the workspace connection exists but you personally haven't authorized, open the NetSuite connector's **Authorizations** tab — your **Your NetSuite user** card will read **Authorization required**. Click **Authorize** and approve in the NetSuite popup.

    <Warning>
      The connect and authorize flows open a NetSuite popup and poll for completion. If nothing happens, your browser is likely blocking popups — allow popups for Erstan and try again.
    </Warning>
  </Accordion>

  <Accordion title="NetSuite authorization expired or unhealthy" icon="key-round">
    NetSuite access tokens are short-lived (roughly one hour), and Erstan refreshes them automatically in the background. If a refresh fails or the connection goes stale, you'll see **Authorization expired** or **Endpoint unhealthy** on the connector.

    <Steps>
      <Step title="Re-authenticate your user">
        On the **Authorizations** tab, click **Re-authorize** on your **Your NetSuite user** card and approve in the NetSuite popup. This re-grants access using your own NetSuite role.
      </Step>

      <Step title="Test the workspace connection">
        Owners and admins can open the **Setup** tab and use **Test connection**, then **Test token refresh** to confirm the workspace OAuth connection can renew tokens.
      </Step>
    </Steps>

    See [Connection troubleshooting](/connectors/troubleshooting) for the full list of statuses and what each one means.
  </Accordion>

  <Accordion title="A 'NetSuite is busy' / Queued card appears" icon="hourglass">
    When NetSuite is handling other work, Erstan briefly holds a request and shows a **Queued — NetSuite** card. This is informational only — it has no buttons and **resumes automatically** when capacity frees up.

    <Note>
      A Queued card is intentionally different from an approval card. It means "waiting its turn," not "waiting for you." There's nothing to click; leave it and the run continues on its own.
    </Note>

    If a run sits queued far longer than expected, check the connector's status — an expired authorization (above) can stall work that's waiting on NetSuite.
  </Accordion>

  <Accordion title="An approval card didn't appear (or appeared when you didn't expect)" icon="shield-check">
    Writes to NetSuite and other systems pause for you by default: you see an approval card with **Run action** / **Don't run** before anything is changed. If a write happened without prompting, **Auto-approve writes** is likely on.

    * **Auto-approve writes** is toggled from the chat composer's **+** menu and is remembered in your browser. It only applies in plain chat with the default **Erstan** assistant — not to custom agents you've built or @mentioned.
    * For agents, whether a tool prompts is set by its **write policy** per tool: **Allow**, **Require approval**, or **Deny** (see [Managing NetSuite: tools & write policy](/connectors/netsuite-manage)).

    <Warning>
      Auto-approve lets agents write to your ERP without a confirmation step. Turn it on only for low-risk, well-understood tasks, and turn it back off when you're done. Review the full behavior in [Approving and rejecting AI actions](/chat/approvals).
    </Warning>
  </Accordion>

  <Accordion title="An 'Authorization required' card shows mid-chat" icon="shield-check">
    If an agent reaches for a connected system you haven't authorized yet, chat surfaces an **Authorization required** card. Authorize the account from the card (or from the connector's **Authorizations** tab), then continue the conversation — the run picks up where it left off.
  </Accordion>

  <Accordion title="A run looks stuck or stale" icon="refresh-cw">
    Run details stream live. If a run is idle for a long time, it shows a **stale** status with a **Refresh trace** (or **Retry Run**) affordance.

    <Steps>
      <Step title="Refresh the trace">
        Click **Refresh trace** to re-sync the run's live status. Long-idle runs often just need a refresh to show their latest state.
      </Step>

      <Step title="Check for a waiting approval">
        A run can pause indefinitely on an approval or an Authorization required card. Open the run and respond so it can resume.
      </Step>

      <Step title="Retry if it failed">
        If the run errored, use **Retry Run** from the run detail. Review the step trace first to see where it stopped — see [Run history, traces & analytics](/agents/run-history-traces).
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="An agent won't run" icon="circle-slash">
    An agent can't start for a few specific reasons. The library or run dialog will tell you which one applies:

    | Reason                               | What to do                                                                                                          |
    | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
    | Status is **Archived**               | Restore or duplicate the agent before running it.                                                                   |
    | No runnable **trigger / start step** | Open the [builder](/agents/builder) and add a trigger or start step.                                                |
    | A required **connection is missing** | Connect or authorize the system shown in the **Connection required** banner.                                        |
    | A run is **already active**          | Wait for the current run to finish, then start a new one.                                                           |
    | Trigger **Run As** not set           | For scheduled/triggered agents, configure and consent to **Run As** before [publishing](/agents/publish-lifecycle). |
  </Accordion>
</AccordionGroup>

## Getting help

If you've worked through the relevant fix above and an issue persists, gather the details that speed up support: the workspace name, the agent or chat involved, and the run's trace (use **Audit in Erstan** from a run for the full record). Then reach out to your Erstan contact or workspace Owner.

<Info>
  Erstan is in **Beta**. Some surfaces are still changing, and a few connectors are marked **Coming soon** and can't be connected yet.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Connection troubleshooting" icon="plug" href="/connectors/troubleshooting">
    Connection statuses, re-authenticating, and token lifetimes in depth.
  </Card>

  <Card title="Approving AI actions" icon="shield-check" href="/chat/approvals">
    How write approvals, auto-approve, and queued cards work.
  </Card>

  <Card title="Run history & traces" icon="activity" href="/agents/run-history-traces">
    Read a run's step-by-step trace to find where it stopped.
  </Card>

  <Card title="Security & write safety" icon="lock" href="/security/overview">
    How Erstan keeps you in control of every NetSuite change.
  </Card>
</CardGroup>