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

# Troubleshooting

> Quick fixes for the most common Braintrust user issues.

<Callout color="#007AFF">
  **Quick Triage — run these four checks first:**

  1. Is the issue in a **DM** or a **group Space**?
  2. Is the expert hired and configured (no warning badge)?
  3. In group Spaces — did you include `@BrainTrust` in your message?
  4. Try once more with a shorter, simpler prompt.
</Callout>

## Common Issues

| Symptom                              | Likely Cause                            | Fix                                                        |
| ------------------------------------ | --------------------------------------- | ---------------------------------------------------------- |
| No response in group Space           | No experts added, or missing mention    | Run `/list`, add expert with `/add`, include `@BrainTrust` |
| `/add` fails                         | Wrong email or expert not hired         | Verify email on expert page and hire first                 |
| Expert says setup required           | Missing credentials                     | Open expert page and run **Configure**                     |
| Stuck on "Thinking..."               | Timeout or temporary load               | Wait briefly, retry once, simplify prompt                  |
| Wrong expert responds in group Space | Ambiguous request or weak routing rules | Write a more specific prompt or set `/orchestrator` rules  |
| Cannot remove expert                 | Expert not in current group Space       | Run `/list` then `/remove <exact-email>`                   |

## Credential Problems

| Problem                           | Fix                                          |
| --------------------------------- | -------------------------------------------- |
| OAuth popup blocked               | Allow popups for Braintrust domain and retry |
| API key/token rejected            | Replace with valid key/token and re-save     |
| Previously working tool now fails | Reconfigure; token may have expired/revoked  |

## Automation Problems

| Problem                       | Fix                                                       |
| ----------------------------- | --------------------------------------------------------- |
| Cron trigger did not run      | Check trigger is enabled and schedule/timezone is correct |
| Calendar trigger not firing   | Reconnect calendar integration, then test again           |
| Output appears in wrong place | Verify trigger delivery target (DM vs group Space)        |

## If It Still Fails

Collect this before asking for help:

* Exact error text
* Expert name/email
* Whether issue was in DM or group Space
* Command/prompt used
* Approximate timestamp

## Agent Hung or Frozen

<Warning>
  **Symptom:** The expert shows "Thinking..." indefinitely with no response or the response seems to stop in midway.
</Warning>

**Common causes:**

1. **A tool call is taking very long.** Some operations — like a NetSuite heavy query or a QuickBooks `fetchAll` with no date bounds — can take several minutes.
2. **Rare: the agent is frozen** waiting for a response that was dropped due to a transient error.

**What to do:**

* Wait up to **5 minutes** for slow tool calls to complete.
* If still stuck after 5 minutes, send a new message to start a fresh interaction.

**Prevention:**

* Use specific date ranges in data queries.
* Avoid `fetchAll` without filters.
* Break large requests into smaller, scoped queries.

## Getting a Fresh Start

If an expert is consistently misbehaving, try these steps in order:

1. **Reset context:** Send "Start fresh" or "Forget the previous context" to clear the conversation state.
2. **Reconfigure credentials:** If tools are failing, open the expert page and click **Configure** to re-enter credentials.
3. **Re-hire the expert:** Un-hire and re-hire the expert. This creates a new instance with fresh state.
4. **Contact the expert owner:** If the expert itself seems broken (not just your instance), reach out to the builder to check for issues with the expert's configuration.

## Credential Type Quick Reference

| Credential Type             | When You Get This                      | How to Enter It                          | Common Expiry Issues                                       |
| --------------------------- | -------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
| **OAuth (Connect Account)** | Sign-in flow from the provider         | Click Connect, sign in with your account | Token expires if not used, or if OAuth app is deauthorized |
| **API Key**                 | Static string from provider dashboard  | Paste into the key field                 | Keys can be revoked or rotated by the provider             |
| **Bearer Token**            | Short-lived token string               | Paste into the token field               | Often expires in hours or days                             |
| **Basic Auth**              | Username + password                    | Enter in two separate fields             | Password changes break the connection                      |
| **Environment Variable**    | Field values defined by expert creator | Enter the value as labeled               | Check with expert owner for expected format                |

## Next Steps

<CardGroup cols={2}>
  <Card title="Slash Commands" icon="terminal" color="#007AFF" href="/reference/slash-commands" arrow={true}>
    Validate command syntax and expected behavior.
  </Card>

  <Card title="Connecting Tools and Integrations" icon="plug" color="#FF9500" href="/experts/configuring-agent-tools" arrow={true}>
    Re-run credential setup safely.
  </Card>

  <Card title="Using Multiple Experts Together" icon="people-group" color="#34C759" href="/experts/multi-agent-collaboration" arrow={true}>
    Improve group Space routing quality.
  </Card>

  <Card title="Glossary" icon="book-open" color="#5856D6" href="/reference/glossary" arrow={true}>
    Clarify terms used in errors and docs.
  </Card>
</CardGroup>