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

# Troubleshooting guides

> Resolve errors, debug issues, and fix common problems

Find solutions to common errors, debug system issues, and resolve technical problems. Each guide includes step-by-step resolution steps based on real support cases.

## All troubleshooting guides

> [card] [500 error when iterating over a dataset](https://docs.braintrust.dev/kb/500-error-when-iterating-over-a-dataset)

> [card] [Add tags to scorers using API instead of SDK](https://docs.braintrust.dev/kb/add-tags-to-scorers-using-api-instead-of-sdk)

> [card] [Add to dataset captures root span only](https://docs.braintrust.dev/kb/add-to-dataset-captures-root-span-only)

> [card] [AI Proxy audio compression with x-bt-compress-audio](https://docs.braintrust.dev/kb/ai-proxy-audio-compression-with-x)

> [card] [Alert aggregation not supported for error rates](https://docs.braintrust.dev/kb/alert-aggregation-not-supported-for-error-rates)

> [card] [API keys cannot create API keys via impersonation](https://docs.braintrust.dev/kb/api-keys-cannot-create-api-keys-via-impersonation)

> [card] [API rate limits during backfill operations](https://docs.braintrust.dev/kb/api-rate-limits-during-backfill-operations)

> [card] [API URL configuration conflicts in self-hosted deployments](https://docs.braintrust.dev/kb/api-url-configuration-conflicts-in-self)

> [card] [Autoevals Scorer 401 Braintrust gateway error](https://docs.braintrust.dev/kb/autoevals-scorer-401-braintrust-gateway-error)

> [card] [Automation scorer failures due to Gemini gateway routing errors](https://docs.braintrust.dev/kb/automation-scorer-failures-due-to-gemini-gateway-routing-errors)

> [card] [Azure AD client secret rotation SSO failures](https://docs.braintrust.dev/kb/azure-ad-client-secret-rotation-sso-failures.md)

> [card] [Bedrock authorization errors with regional access](https://docs.braintrust.dev/kb/bedrock-authorization-errors-with-regional-access)

> [card] [Bedrock model variations for on-demand throughput](https://docs.braintrust.dev/kb/bedrock-model-variations-for-on-demand-throughput)

> [card] [Bedrock Nova 2 inference-profile IAM and custom provider setup](https://docs.braintrust.dev/kb/bedrock-nova-2-inference-profile-iam-and-custom-provider-setup)

> [card] [Blank comparison rows due to mismatched inputs](https://docs.braintrust.dev/kb/blank-comparison-rows-due-to-mismatched-inputs)

> [card] [Blank iframe requires console log inspection](https://docs.braintrust.dev/kb/blank-iframe-requires-console-log-inspection)

> [card] [Brainstore OOM errors and retry-induced rate limits](https://docs.braintrust.dev/kb/brainstore-oom-errors-and-retry-induced-rate-limits)

> [card] [BTQL Filter Not Applied to All Results: Understanding traces vs spans in project\_logs Queries](https://docs.braintrust.dev/kb/btql-filter-not-applied-to-all-results-understanding-traces-vs-spans-in-project-logs-queries)

> [card] [BTQL rate limits](https://docs.braintrust.dev/kb/btql-rate-limits)

> [card] [BTQL summary queries fail with signBlob permission error](https://docs.braintrust.dev/kb/btql-summary-queries-fail-with-signblob-permission-error)

> [card] [BTQL timeouts caused by oversized row fields](https://docs.braintrust.dev/kb/btql-timeouts-caused-by-oversized-row-fields)

> [card] [Check data plane version in self-hosted deployments](https://docs.braintrust.dev/kb/check-data-plane-version-in-self)

> [card] [Claude Agent SDK API keys recorded in trace metadata](https://docs.braintrust.dev/kb/claude-agent-sdk-api-keys-recorded-in-trace-metadata)

> [card] [Claude Sonnet 4 missing from playground model picker](https://docs.braintrust.dev/kb/claude-sonnet-4-missing-from-playground-model-picker)

> [card] [CLI auth fails for self-hosted deployments with TLS errors](https://docs.braintrust.dev/kb/cli-auth-fails-for-self-hosted-deployments-with-tls-errors)

> [card] [CloudFront 403 errors during evaluator invocation](https://docs.braintrust.dev/kb/cloudfront-403-errors-during-evaluator-invocation)

> [card] [Code scorer fails with pagination key error](https://docs.braintrust.dev/kb/code-scorer-fails-with-pagination-key-error)

> [card] [Code scorer function must be named handler](https://docs.braintrust.dev/kb/code-scorer-function-must-be-named-handler)

> [card] [Configure a custom CA for Python scorers on self-hosted AWS](https://docs.braintrust.dev/kb/python-scorer-custom-ca-bundle-aws-kb)

> [card] [Context length error caused by wrong AI provider routing](https://docs.braintrust.dev/kb/context-length-error-caused-by-wrong-ai-provider-routing)

> [card] [Controlling Concurrency to Prevent Resource Exhaustion](https://docs.braintrust.dev/kb/controlling-concurrency-to-prevent-resource-exhaustion)

> [card] [COUNT(DISTINCT) in GROUP BY returns row count](https://docs.braintrust.dev/kb/count-distinct-in-group-by-returns-row-count)

> [card] [Creating permalinks to log events via API](https://docs.braintrust.dev/kb/creating-permalinks-to-log-events-via-api)

> [card] [Cross-project scorer automation missing read access](https://docs.braintrust.dev/kb/cross-project-scorer-automation-missing-read-access)

> [card] [Cursor Cloud MCP JWT validation error fix](https://docs.braintrust.dev/kb/cursor-cloud-mcp-jwt-validation-error-fix)

> [card] [Custom view code cannot use package imports](https://docs.braintrust.dev/kb/custom-view-code-cannot-use-package-imports)

> [card] [Dashboard logs missing due to span name schema error](https://docs.braintrust.dev/kb/dashboard-logs-missing-due-to-span)

> [card] [Dataset search limited to 1000 records](https://docs.braintrust.dev/kb/dataset-search-limited-to-1000-records)

> [card] [Datetime fields in trace data are normalized to UTC](https://docs.braintrust.dev/kb/timestamps-converted-to-utc-in-traces)

> [card] [Debug hanging eval processes with external dependencies](https://docs.braintrust.dev/kb/debug-hanging-eval-processes-with-external)

> [card] [EMFILE Error (Too Many Open Files) During Evaluations: Controlling Concurrency to Prevent Resource Exhaustion](https://docs.braintrust.dev/kb/emfile-error-too-many-open-files-during-evaluations-controlling-concurrency-to-prevent-resource-exhaustion)

> [card] [Empty traces with flush race conditions](https://docs.braintrust.dev/kb/empty-traces-with-flush-race-conditions)

> [card] [Estimated cost missing in logs table with project-level providers](https://docs.braintrust.dev/kb/estimated-cost-missing-in-logs-table-with-project-level-providers)

> [card] [Eval runner environment variable size limit](https://docs.braintrust.dev/kb/eval-runner-environment-variable-size-limit)

> [card] [Eval timeout errors for initial scorers](https://docs.braintrust.dev/kb/eval-timeout-errors-for-initial-scorers)

> [card] [Failed to fetch full trace in data plane](https://docs.braintrust.dev/kb/failed-to-fetch-full-trace-in-data-plane)

> [card] [Filter logs by topic classification ID](https://docs.braintrust.dev/kb/filter-logs-by-topic-classification-id)

> [card] [Fix “slug already exists” errors for prompts that are not visible](https://docs.braintrust.dev/kb/resolve-invisible-prompt-slug-conflict-with-put)

> [card] [Gateway calls fail in bt eval --dev mode](https://docs.braintrust.dev/kb/gateway-calls-fail-in-bt-eval-dev-mode)

> [card] [GCP checksum mismatch errors after data plane upgrade to v1.1.32](https://docs.braintrust.dev/kb/gcp-checksum-mismatch-after-data-plane-upgrade)

> [card] [GCS Brainstore rate limit errors and retries](https://docs.braintrust.dev/kb/gcs-brainstore-rate-limit-errors-and-retries)

> [card] [Grouping logs by field in UI requires the Query page](https://docs.braintrust.dev/kb/grouping-logs-by-field-in-ui-requires-sql-sandbox)

> [card] [How fixed-amount coupons are applied to invoice charges](https://docs.braintrust.dev/kb/how-fixed-amount-coupons-are-applied-to-invoice-charges)

> [card] [How prompt version IDs work in Braintrust SDKs](https://docs.braintrust.dev/kb/prompt-version-returns-decimal-id-not-ui-hex-string)

> [card] [HTTP 421 errors with self-hosted data planes](https://docs.braintrust.dev/kb/http-421-errors-with-self-hosted-data-planes)

> [card] [Human review assignee cannot see assigned experiments](https://docs.braintrust.dev/kb/human-review-assignee-cannot-see-assigned-experiments)

> [card] [Human review output format: string vs JSON](https://docs.braintrust.dev/kb/human-review-output-format-string-vs-json)

> [card] [Impersonation permissions for service tokens](https://docs.braintrust.dev/kb/impersonation-permissions-for-service-tokens)

> [card] [Internal Server Error: No Secrets Match ORG\_NAME in](https://docs.braintrust.dev/kb/internal-server-error-no-secrets-match)

> [card] [Invoke saved preprocessors from custom code scorers](https://docs.braintrust.dev/kb/invoke-saved-preprocessors-from-custom-code-scorers)

> [card] [Keyboard shortcuts for trace and span navigation](https://docs.braintrust.dev/kb/keyboard-shortcuts-for-trace-and-span-navigation)

> [card] [Large experiment downloads timeout in UI](https://docs.braintrust.dev/kb/large-experiment-downloads-timeout-in-ui)

> [card] [LiteLLM instrumentation may record provider credentials](https://docs.braintrust.dev/kb/litellm-instrumentation-may-record-provider-credentials)

> [card] [loadPrompt caching behavior in TypeScript SDK](https://docs.braintrust.dev/kb/loadprompt-caching-behavior-and-version-fallback)

> [card] [Log filtering with large user ID sets](https://docs.braintrust.dev/kb/log-filtering-with-large-user-id-sets)

> [card] [Log filtering with tags stalls after 50 results](https://docs.braintrust.dev/kb/log-filtering-with-tags-stalls-after-50-results)

> [card] [Logger and experiment span parent type mismatch error](https://docs.braintrust.dev/kb/logger-and-experiment-span-parent-type-mismatch-error)

> [card] [Logs not opening due to checksum instability](https://docs.braintrust.dev/kb/logs-not-opening-due-to-checksum-instability)

> [card] [Logs page broken by custom column expression](https://docs.braintrust.dev/kb/logs-page-broken-by-custom-column-expression)

> [card] [Logs stopped after Brainstore platform update](https://docs.braintrust.dev/kb/logs-stopped-after-brainstore-platform-update)

> [card] [Loop models require Anthropic API key, not just Bedrock](https://docs.braintrust.dev/kb/loop-models-require-anthropic-api-key-not-just-bedrock)

> [card] [Loop selects wrong project: include explicit context](https://docs.braintrust.dev/kb/loop-selects-wrong-project-include-explicit-context)

> [card] [MCP returns empty logs for SaaS org from self-hosted endpoint](https://docs.braintrust.dev/kb/mcp-returns-empty-logs-for-saas-org-from-self-hosted-endpoint)

> [card] [Metadata filtering in custom views shows partial data](https://docs.braintrust.dev/kb/metadata-filtering-in-custom-views-shows)

> [card] [Missing classification values from automated scorer](https://docs.braintrust.dev/kb/missing-classification-values-from-automated-scorer)

> [card] [Missing conversation turns after lightweight de‑id migration](https://docs.braintrust.dev/kb/missing-conversation-turns-after-lightweight-de-id-migration)

> [card] [Missing scorers in automation rules editor](https://docs.braintrust.dev/kb/missing-scorers-in-automation-rules-editor)

> [card] [Missing source preview for a deployed scorer](https://docs.braintrust.dev/kb/missing-source-preview-for-deployed-scorer)

> [card] [Model cost missing when using third-party SDKs](https://docs.braintrust.dev/kb/fireworks-cost-missing-when-using-vercel-ai-sdk)

> [card] [Nested LLM call counting discrepancy](https://docs.braintrust.dev/kb/nested-llm-call-counting-discrepancy)

> [card] [No export-only permission in Braintrust ACL model](https://docs.braintrust.dev/kb/no-export-only-permission-in-braintrust-acl-model)

> [card] [Null input on spans when using OTEL attributes](https://docs.braintrust.dev/kb/null-input-on-spans-when-using-otel-attributes)

> [card] [Okta SAML tile login fails with missing RelayState](https://docs.braintrust.dev/kb/okta-saml-tile-login-fails-with-missing-relaystate)

> [card] [Online scorer deduplication with concurrent feedback](https://docs.braintrust.dev/kb/online-scorer-deduplication-with-concurrent-feedback)

> [card] [Online scorers not finding production traces](https://docs.braintrust.dev/kb/online-scorers-not-finding-production-traces-time-based-filter-issues-and-query-best-practices)

> [card] [Online scoring results not visible in UI](https://docs.braintrust.dev/kb/online-scoring-results-not-visible-in-ui-understanding-async-scoring-and-alert-timing)

> [card] [Online scoring rule failing after SDK update](https://docs.braintrust.dev/kb/online-scoring-rule-failing-after-sdk-update)

> [card] [OpenAI regional endpoint troubleshooting](https://docs.braintrust.dev/kb/openai-regional-endpoint-troubleshooting)

> [card] [OTEL metadata mapping and attachment rendering with PydanticAI](https://docs.braintrust.dev/kb/otel-metadata-mapping-and-attachment-rendering-with-pydanticai)

> [card] [OTLP traces endpoint payload limits](https://docs.braintrust.dev/kb/otlp-traces-endpoint-payload-limits.md)

> [card] [Playground gateway error despite valid API keys](https://docs.braintrust.dev/kb/playground-gateway-error-despite-valid-api-keys)

> [card] [Playground timeout with long-running model requests](https://docs.braintrust.dev/kb/playground-timeout-with-long-running-model)

> [card] [Populate project names in list prompts API](https://docs.braintrust.dev/kb/populate-project-names-in-list-prompts-api)

> [card] [Prepare grouping fields for group-scoped rules](https://docs.braintrust.dev/kb/group-scoped-rules-require-ui-index-provisioning)

> [card] [Python scorer fails with an import error on self-hosted deployments](https://docs.braintrust.dev/kb/python-scorer-import-error-self-hosted)

> [card] [Recover a deleted or inaccessible project](https://docs.braintrust.dev/kb/project-disappeared-or-inaccessible-data-recovery)

> [card] [Prompt shows None in experiment view](https://docs.braintrust.dev/kb/prompt-shows-none-in-experiment-view)

> [card] [PydanticAI integration counts wrapper spans as LLM calls](https://docs.braintrust.dev/kb/pydanticai-integration-counts-wrapper-spans-as)

> [card] [Query timeout requires timestamp filter](https://docs.braintrust.dev/kb/query-timeout-requires-timestamp-filter)

> [card] [Rate limit error during dataset iteration](https://docs.braintrust.dev/kb/rate-limit-error-during-dataset-iteration)

> [card] [Recover or retrieve a deleted prompt](https://docs.braintrust.dev/kb/recover-or-retrieve-a-deleted-prompt)

> [card] [Recovering deleted experiment rows with versioned BTQL queries](https://docs.braintrust.dev/kb/recovering-deleted-experiment-rows)

> [card] [Remote eval dev mode fails with Pydantic parameters](https://docs.braintrust.dev/kb/remote-eval-dev-mode-fails-with-pydantic-parameters)

> [card] [Remote evals firewall egress and auth troubleshooting](https://docs.braintrust.dev/kb/remote-evals-firewall-egress-and-auth-troubleshooting)

> [card] [Repair unhealthy Topics automation references](https://docs.braintrust.dev/kb/repair-unhealthy-topics-automation-references)

> [card] [Row-level change history and bulk upsert behavior](https://docs.braintrust.dev/kb/row-level-change-history-and-bulk-upsert-behavior)

> [card] [Rows not attached to a dataset or experiment](https://docs.braintrust.dev/kb/dataset-not-linked-to-experiment-when-using-evalasync-with-parent)

> [card] [Run evaluations on large datasets in Playgrounds or the SDK](https://docs.braintrust.dev/kb/run-evals-on-large-datasets-playground-or-sdk)

> [card] [SAML login fails with email domain mismatch](https://docs.braintrust.dev/kb/saml-login-fails-with-email-domain-mismatch)

> [card] [Score logs by Topics facet values with batch scoring](https://docs.braintrust.dev/kb/facets-field-unavailable-in-automation-sql-filters)

> [card] [Scorer overwriting human review data with identical names](https://docs.braintrust.dev/kb/scorer-overwriting-human-review-data-with)

> [card] [Scorer pane columns collapse on open](https://docs.braintrust.dev/kb/scorer-pane-columns-collapse-on-open)

> [card] [Scores added via API not displaying in UI](https://docs.braintrust.dev/kb/scores-added-via-api-not-displaying-in-ui)

> [card] [SDK rate limits during dataset iteration](https://docs.braintrust.dev/kb/sdk-rate-limits-during-dataset-iteration)

> [card] [Search Timeout on Log Queries: CAST Operations in Custom](https://docs.braintrust.dev/kb/search-timeout-on-log-queries-cast)

> [card] [Securing remote eval endpoints: authentication and](https://docs.braintrust.dev/kb/securing-remote-eval-endpoints-authentication-and)

> [card] [Self-hosted multi-org data plane automation troubleshooting](https://docs.braintrust.dev/kb/self-hosted-multi-org-data-plane-automation-troubleshooting)

> [card] [Span components v4 encoding error on self-hosted after upgrading the SDK](https://docs.braintrust.dev/kb/span-components-v4-encoding-error-on-self-hosted-after-sdk-upgrade)

> [card] [Span Name Filtering Not Working on Monitoring Page:](https://docs.braintrust.dev/kb/span-name-filtering-not-working-on)

> [card] [SpanComponents encoding error when attaching feedback spans](https://docs.braintrust.dev/kb/spancomponents-encoding-error-when-attaching-feedback-spans)

> [card] [SQL queries timeout when missing timestamp filter](https://docs.braintrust.dev/kb/sql-queries-timeout-when-missing-timestamp-filter)

> [card] [SSL certificate verification failure behind corporate proxy](https://docs.braintrust.dev/kb/ssl-certificate-verification-failure-behind-corporate-proxy)

> [card] [SSO login fails with 'did not grant access' error](https://docs.braintrust.dev/kb/sso-login-fails-with-did-not-grant-access-error)

> [card] [Strict mode omits required field in structured output](https://docs.braintrust.dev/kb/strict-mode-omits-required-field-in-structured-output)

> [card] [Subquery alias conflicts with column names](https://docs.braintrust.dev/kb/unpivot-subquery-alias-conflicts-with-column-names)

> [card] [Tag filter dropdown missing tags from logged data](https://docs.braintrust.dev/kb/tag-filter-dropdown-missing-tags-from-logged-data)

> [card] [Temperature parameter included in GPT-5 prompts from SDK](https://docs.braintrust.dev/kb/temperature-parameter-included-in-gpt-5)

> [card] [Temperature parameter not supported in GPT-5 models](https://docs.braintrust.dev/kb/temperature-parameter-not-supported-in-gpt)

> [card] [Topics facets empty due to Skipped status](https://docs.braintrust.dev/kb/topics-facets-empty-due-to-skipped-status)

> [card] [Trace gaps when exported span context is not persisted across restarts](https://docs.braintrust.dev/kb/trace-gaps-when-parent-span-export-is-not-persisted-across-restarts)

> [card] [Trace-scoped automation scores missing from Monitor charts](https://docs.braintrust.dev/kb/backfilled-trace-scores-missing-from-monitor-charts)

> [card] [Trace scorers rerun due to metrics.end updates](https://docs.braintrust.dev/kb/trace-scorers-rerun-due-to-metrics-end-updates)

> [card] [Tracing Anthropic models via LiteLLM with Braintrust](https://docs.braintrust.dev/kb/tracing-anthropic-models-via-litellm-with-braintrust)

> [card] [Transient JSONL.GZ files in S3 export bucket](https://docs.braintrust.dev/kb/transient-jsonl-gz-files-in-s3-export-bucket)

> [card] [Trial quota limits and monthly reset cycle](https://docs.braintrust.dev/kb/trial-quota-limits-and-monthly-reset-cycle)

> [card] [Troubleshoot 'No projects are available'](https://docs.braintrust.dev/kb/troubleshoot-no-projects-are-available)

> [card] [Troubleshoot a slow or unresponsive Logs page](https://docs.braintrust.dev/kb/logs-page-frozen-by-custom-column-expressions)

> [card] [Troubleshoot Braintrust alerts not appearing in incident.io](https://docs.braintrust.dev/kb/troubleshoot-braintrust-alerts-not-appearing-in-incident-io)

> [card] [Troubleshooting Organization Changes in Self-Hosted Data](https://docs.braintrust.dev/kb/troubleshooting-organization-changes-in-self-hosted)

> [card] [Troubleshooting Traces Stuck in Progress](https://docs.braintrust.dev/kb/troubleshooting-traces-stuck-in-progress)

> [card] [TypeScript SDK eval process hangs after completion](https://docs.braintrust.dev/kb/typescript-sdk-eval-process-hangs-after-completion-debugging-open-handles-and-resource-leaks)

> [card] [UI cache hit rate shows zero with raw metrics](https://docs.braintrust.dev/kb/ui-cache-hit-rate-shows-zero-with-raw-metrics)

> [card] [Understanding Brainstore query optimization warning logs](https://docs.braintrust.dev/kb/understanding-brainstore-query-optimization-warning-logs)

> [card] [Understanding traces vs spans in SQL & BTQL queries](https://docs.braintrust.dev/kb/understanding-traces-vs-spans-in-sql-btql-queries)

> [card] [Unexpected "Created" dates appearing under a "Created between" filter](https://docs.braintrust.dev/kb/traces-vs-spans-created-filter-and-date-discrepancies)

> [card] [Unexpected score columns in Logs](https://docs.braintrust.dev/kb/empty-automation-column-persists-after-scorer-deletion)

> [card] [Use custom preprocessor to fix missing Topics facet](https://docs.braintrust.dev/kb/fix-missing-topics-facet-with-custom-preprocessor.mdx)

> [card] [Vertex AI gemini model region and registry issues](https://docs.braintrust.dev/kb/vertex-ai-gemini-model-region-and-registry-issues)

> [card] [wrapAISDK interleaved traces with concurrent calls](https://docs.braintrust.dev/kb/wrapaisdk-interleaved-traces-with-concurrent-calls)

## Need more help?

Can't find what you're looking for? Search across all documentation using the search bar above, or contact support at [support@braintrust.dev](mailto:support@braintrust.dev).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.