Quick Triage — run these four checks first:
- Is the issue in a DM or a group Space?
- Is the expert hired and configured (no warning badge)?
- In group Spaces — did you include
@BrainTrustin your message? - Try once more with a shorter, simpler prompt.
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
Common causes:- A tool call is taking very long. Some operations — like a NetSuite heavy query or a QuickBooks
fetchAllwith no date bounds — can take several minutes. - Rare: the agent is frozen waiting for a response that was dropped due to a transient error.
- 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.
- Use specific date ranges in data queries.
- Avoid
fetchAllwithout filters. - Break large requests into smaller, scoped queries.
Getting a Fresh Start
If an expert is consistently misbehaving, try these steps in order:- Reset context: Send “Start fresh” or “Forget the previous context” to clear the conversation state.
- Reconfigure credentials: If tools are failing, open the expert page and click Configure to re-enter credentials.
- Re-hire the expert: Un-hire and re-hire the expert. This creates a new instance with fresh state.
- 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
Slash Commands
Validate command syntax and expected behavior.
Connecting Tools and Integrations
Re-run credential setup safely.
Using Multiple Experts Together
Improve group Space routing quality.
Glossary
Clarify terms used in errors and docs.