Learn about Braintrust’s system behavior, technical architecture, and internal processes. These guides explain how features work under the hood.Documentation Index
Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
All troubleshooting guides
- Overview
- Troubleshooting guides
- Config guides
- Process & systems
- 500 error when iterating over a dataset
- Access UI parameters in remote eval tasks
- Accessing log attachments in Python scorers
- Add custom measures to monitoring charts
- Add tags to scorers using API instead of SDK
- Add to dataset captures root span only
- AI Proxy audio compression with x-bt-compress-audio
- Alert aggregation not supported for error rates
- API rate limits during backfill operations
- API URL configuration conflicts in self-hosted deployments
- Apply log retention policies across all projects via API
- Attaching debuggers to Braintrust eval CLI
- AWS Bedrock IAM permissions for Braintrust integration
- Bedrock authorization errors with regional access
- Bedrock model variations for on-demand throughput
- Blank comparison rows due to mismatched inputs
- Blank iframe requires console log inspection
- How multi-reviewer scoring works in human review
- Brainstore OOM errors and retry-induced rate limits
- BTQL Filter Not Applied to All Results: Understanding traces vs spans in project_logs Queries
- BTQL POST endpoint payload and response schema
- BTQL summary queries fail with signBlob permission error
- BTQL rate limits on free and pro plans
- Chart not visible after creation on monitoring page
- Check data plane version in self-hosted deployments
- Claude Desktop MCP OAuth Failures
- Claude Desktop MCP streaming connection failures
- CloudFront 403 errors during evaluator invocation
- Code scorer fails with pagination key error
- Code scorer function must be named handler
- Configure custom model costs for estimation
- Configure dataset schemas via API
- Configure default groups for Google SSO users
- Configure human review visibility in dataset views
- Configure MCP server with self-hosted data plane
- Configure root span filter for online scoring
- Configure scorer pass threshold via API
- Controlling Concurrency to Prevent Resource Exhaustion
- COUNT(DISTINCT) in GROUP BY returns row count
- Create monitoring dashboards with organization permissions
- Creating permalinks to log events via API
- Custom view code cannot use package imports
- Creating prompts with encoded custom provider model names
- Customizing experiment names in the SDK
- Customizing Monitoring Views: Removing Charts and Managing View Layouts
- Dashboard logs missing due to span name schema error
- Dataset format for system and user prompts
- Rows not attached to a dataset or experiment
- Dataset search limited to 1000 records
- Debug hanging eval processes with external dependencies
- Defining response schema in prompts.create()
- Detecting Remote Eval and CLI Execution Context: SDK Hooks and Environment Variables
- Duplicate a prompt in Braintrust
- Edit Topics automation sampling rate after setup
- EMFILE Error (Too Many Open Files) During Evaluations: Controlling Concurrency to Prevent Resource Exhaustion
- Emit traces to multiple projects simultaneously
- Empty traces with flush race conditions
- Eval timeout errors for initial scorers
- Experiment Fetch Limited to 1000 Events - Export All
- Export all experiment events using BTQL pagination
- Failed to fetch full trace in data plane
- Fetching human review comments via API and BTQL
- File attachment support across models
- Filter logs by tags and scores with ANY_SPAN
- Model cost missing when using third-party SDKs
- Flagging logs and users for review via API
- Flagging users for review via API
- GCS Brainstore rate limit errors and retries
- GCP checksum mismatch errors after data plane upgrade to v1.1.32
- Generate stable experiment permalinks
- Grouping logs by field in UI requires SQL sandbox
- How to configure OpenAI for EU organizations
- How to duplicate views across projects
- How to Find and Use Self-Hosted Data Plane API Endpoints
- How to Save Custom Instructions for Loop Using Project
- HTTP 421 errors with self-hosted data planes
- Human review output format: string vs JSON
- Human review visibility in experiment row view
- Human review with multiple scores in expected field
- Internal Server Error: No Secrets Match ORG_NAME in
- Java SDK proxy configuration with authentication
- Kubernetes Readiness Probe Hangs on /status Endpoint
- Large experiment downloads timeout in UI
- Log filtering with large user ID sets
- Log token metrics to @traced spans manually
- Log user feedback selectively with init_logger
- Logger and experiment span parent type mismatch error
- Logs not opening due to checksum instability
- Logs stopped after Brainstore platform update
- Loop models require Anthropic API key, not just Bedrock
- Loop security model and user permissions
- Managing Prompt Updates in Production: Environment Tags
- Managing your organization's support requests
- Metadata filtering in custom views shows partial data
- Missing classification values from automated scorer
- Missing scorers in automation rules editor
- Navigate and filter metadata arrays by index
- Nested LLM call counting discrepancy
- No export-only permission in Braintrust ACL model
- Online scorer deduplication with concurrent feedback
- Online Scorers Not Finding Production Traces: Time-Based Filter Issues and Query Best Practices
- Online Scoring Results Not Visible in UI: Understanding Async Scoring and Alert Timing
- Online scoring rule failing after SDK update
- Open trace URLs in a specific view mode
- Optimize large trace logging with attachments
- Org-wide API key auditing is UI-only
- Override custom providers at project level
- Project-level permission groups do not grant cross-project scorer access
- Playground timeout with long-running model requests
- Populate project names in list prompts API
- Project Disappeared or Inaccessible: Data Recovery and
- Project permission levels and user access control
- Project-scoped access with service tokens
- Promoting Prompts Across Environments via API: Complete Workflow for Dev, Staging, and Production
- Prompt diff feature has 4096 character limit
- Prompt shows None in experiment view
- PydanticAI integration counts wrapper spans as LLM calls
- Python SDK Docker containerization setup
- Query multiple projects for combined metrics
- Query scorer span token costs with SQL
- Query timeout requires timestamp filter
- Rate limit error during dataset iteration
- Re-running scorers without re-running tasks
- Recovering deleted experiment rows with versioned BTQL queries
- Removing charts from the default "All Data" view
- Restrict AI provider access using project permissions
- Restrict user access to specific projects only
- Review specific rows in Logs and Experiments
- Route requests to specific AI providers
- Running Evaluations Per Git Commit: SHA-Based Experiment
- Export missing child spans
- Scorer overwriting human review data with identical names
- Scorer template variable reference
- Scores added via API not displaying in UI
- SDK rate limits during dataset iteration
- Search Timeout on Log Queries: CAST Operations in Custom
- Securing remote eval endpoints: authentication and
- Setting up SSO integration in Braintrust
- Slack alert permissions in project settings
- Span Name Filtering Not Working on Monitoring Page:
- SQL queries timeout when missing timestamp filter
- Stitch multi-turn chat into one trace with wrapAISDK
- Tag filter dropdown missing tags from logged data
- Temperature parameter error in prompt editor
- Temperature parameter included in GPT-5 prompts from SDK
- Temperature parameter not supported in GPT-5 models
- Thread view span extraction and filtering
- Trace gaps when exported span context is not persisted across restarts
- Topics automation idle timeout and trace update behavior
- Tracing OpenAI Realtime API with WebSockets
- Transient JSONL.GZ files in S3 export bucket
- Trial quota limits and monthly reset cycle
- Troubleshooting 500 errors in self-hosted data planes
- Troubleshooting Organization Changes in Self-Hosted Data
- Troubleshooting Traces Stuck in Progress
- Understanding Brainstore query optimization warning logs
- TypeScript SDK Eval Process Hangs After Completion: Debugging Open Handles and Resource Leaks
- UI experiment timeout configuration for self-hosted k8s
- Understanding BTQL SQL linter warnings
- Understanding Experiment Score Aggregation: Simple vs
- Understanding traces vs spans in SQL & BTQL queries
- Understanding Update Project ACLs
- Update AWS Bedrock credentials using API
- Use project IDs to prevent duplicate projects after rename
- User Engagement Tracking
- Using OpenAI Responses API with Braintrust SDKs
- wrapAISDK interleaved traces with concurrent calls
All troubleshooting guides
Process & systems
Understand system behavior and technical architecture
Was this page helpful?
⌘I