Troubleshooting - Braintrust Docs

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 @BrainTrust in 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

Symptom: The expert shows “Thinking…” indefinitely with no response or the response seems to stop in midway.

Common causes:

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.
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:

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.

​Common Issues

​Credential Problems

​Automation Problems

​If It Still Fails

​Agent Hung or Frozen

​Getting a Fresh Start

​Credential Type Quick Reference

​Next Steps

Slash Commands

Connecting Tools and Integrations

Using Multiple Experts Together

Glossary

Common Issues

Credential Problems

Automation Problems

If It Still Fails

Agent Hung or Frozen

Getting a Fresh Start

Credential Type Quick Reference

Next Steps