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

# 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

<CardGroup cols={1}>
  <Card title="500 error when iterating over a dataset" href="/kb/500-error-when-iterating-over-a-dataset" />

  <Card title="Add tags to scorers using API instead of SDK" href="/kb/add-tags-to-scorers-using-api-instead-of-sdk" />

  <Card title="Add to dataset captures root span only" href="/kb/add-to-dataset-captures-root-span-only" />

  <Card title="AI Proxy audio compression with x-bt-compress-audio" href="/kb/ai-proxy-audio-compression-with-x" />

  <Card title="Alert aggregation not supported for error rates" href="/kb/alert-aggregation-not-supported-for-error-rates" />

  <Card title="API keys cannot create API keys via impersonation" href="/kb/api-keys-cannot-create-api-keys-via-impersonation" />

  <Card title="API rate limits during backfill operations" href="/kb/api-rate-limits-during-backfill-operations" />

  <Card title="API URL configuration conflicts in self-hosted deployments" href="/kb/api-url-configuration-conflicts-in-self" />

  <Card title="Assigned To column not available in Logs view" href="/kb/assigned-to-column-not-available-in-logs-view" />

  <Card title="Autoevals Scorer 401 Braintrust gateway error" href="/kb/autoevals-scorer-401-braintrust-gateway-error" />

  <Card title="Automation scorer failures due to Gemini gateway routing errors" href="/kb/automation-scorer-failures-due-to-gemini-gateway-routing-errors" />

  <Card title="Azure AD client secret rotation SSO failures" href="/kb/azure-ad-client-secret-rotation-sso-failures" />

  <Card title="Bedrock authorization errors with regional access" href="/kb/bedrock-authorization-errors-with-regional-access" />

  <Card title="Bedrock model variations for on-demand throughput" href="/kb/bedrock-model-variations-for-on-demand-throughput" />

  <Card title="Bedrock Nova 2 inference-profile IAM and custom provider setup" href="/kb/bedrock-nova-2-inference-profile-iam-and-custom-provider-setup" />

  <Card title="Blank comparison rows due to mismatched inputs" href="/kb/blank-comparison-rows-due-to-mismatched-inputs" />

  <Card title="Blank iframe requires console log inspection" href="/kb/blank-iframe-requires-console-log-inspection" />

  <Card title="Brainstore OOM errors and retry-induced rate limits" href="/kb/brainstore-oom-errors-and-retry-induced-rate-limits" />

  <Card title="BTQL Filter Not Applied to All Results: Understanding traces vs spans in project_logs Queries" href="/kb/btql-filter-not-applied-to-all-results-understanding-traces-vs-spans-in-project-logs-queries" />

  <Card title="BTQL rate limits on Starter and Pro plans" href="/kb/btql-rate-limits-on-free-and-pro-plans" />

  <Card title="BTQL summary queries fail with signBlob permission error" href="/kb/btql-summary-queries-fail-with-signblob-permission-error" />

  <Card title="Chart not visible after creation on monitoring page" href="/kb/chart-not-visible-after-creation-on-monitoring-page" />

  <Card title="Check data plane version in self-hosted deployments" href="/kb/check-data-plane-version-in-self" />

  <Card title="Claude Code tracing not working after setup" href="/kb/claude-code-tracing-not-working-after-setup" />

  <Card title="Claude Sonnet 4 missing from playground model picker" href="/kb/claude-sonnet-4-missing-from-playground-model-picker" />

  <Card title="CLI auth fails for self-hosted deployments with TLS errors" href="/kb/cli-auth-fails-for-self-hosted-deployments-with-tls-errors" />

  <Card title="CloudFront 403 errors during evaluator invocation" href="/kb/cloudfront-403-errors-during-evaluator-invocation" />

  <Card title="Code scorer fails with pagination key error" href="/kb/code-scorer-fails-with-pagination-key-error" />

  <Card title="Code scorer function must be named handler" href="/kb/code-scorer-function-must-be-named-handler" />

  <Card title="Context length error caused by wrong AI provider routing" href="/kb/context-length-error-caused-by-wrong-ai-provider-routing" />

  <Card title="Controlling Concurrency to Prevent Resource Exhaustion" href="/kb/controlling-concurrency-to-prevent-resource-exhaustion" />

  <Card title="COUNT(DISTINCT) in GROUP BY returns row count" href="/kb/count-distinct-in-group-by-returns-row-count" />

  <Card title="Creating permalinks to log events via API" href="/kb/creating-permalinks-to-log-events-via-api" />

  <Card title="Cross-project scorer automation missing read access" href="/kb/cross-project-scorer-automation-missing-read-access" />

  <Card title="Cursor Cloud MCP JWT validation error fix" href="/kb/cursor-cloud-mcp-jwt-validation-error-fix" />

  <Card title="Custom view code cannot use package imports" href="/kb/custom-view-code-cannot-use-package-imports" />

  <Card title="Dashboard logs missing due to span name schema error" href="/kb/dashboard-logs-missing-due-to-span" />

  <Card title="Dataset search limited to 1000 records" href="/kb/dataset-search-limited-to-1000-records" />

  <Card title="Debug hanging eval processes with external dependencies" href="/kb/debug-hanging-eval-processes-with-external" />

  <Card title="EMFILE Error (Too Many Open Files) During Evaluations: Controlling Concurrency to Prevent Resource Exhaustion" href="/kb/emfile-error-too-many-open-files-during-evaluations-controlling-concurrency-to-prevent-resource-exhaustion" />

  <Card title="Empty traces with flush race conditions" href="/kb/empty-traces-with-flush-race-conditions" />

  <Card title="Estimated cost missing in logs table with project-level providers" href="/kb/estimated-cost-missing-in-logs-table-with-project-level-providers" />

  <Card title="Eval timeout errors for initial scorers" href="/kb/eval-timeout-errors-for-initial-scorers" />

  <Card title="Failed to fetch full trace in data plane" href="/kb/failed-to-fetch-full-trace-in-data-plane" />

  <Card title="Fix “slug already exists” errors for prompts that are not visible" href="/kb/resolve-invisible-prompt-slug-conflict-with-put" />

  <Card title="Gateway calls fail in bt eval --dev mode" href="/kb/gateway-calls-fail-in-bt-eval-dev-mode" />

  <Card title="GCP checksum mismatch errors after data plane upgrade to v1.1.32" href="/kb/gcp-checksum-mismatch-after-data-plane-upgrade" />

  <Card title="GCS Brainstore rate limit errors and retries" href="/kb/gcs-brainstore-rate-limit-errors-and-retries" />

  <Card title="Grouping logs by field in UI requires SQL sandbox" href="/kb/grouping-logs-by-field-in-ui-requires-sql-sandbox" />

  <Card title="How prompt version IDs work in Braintrust SDKs" href="/kb/prompt-version-returns-decimal-id-not-ui-hex-string" />

  <Card title="HTTP 421 errors with self-hosted data planes" href="/kb/http-421-errors-with-self-hosted-data-planes" />

  <Card title="Human review assignee cannot see assigned experiments" href="/kb/human-review-assignee-cannot-see-assigned-experiments" />

  <Card title="Human review output format: string vs JSON" href="/kb/human-review-output-format-string-vs-json" />

  <Card title="Internal Server Error: No Secrets Match ORG_NAME in" href="/kb/internal-server-error-no-secrets-match" />

  <Card title="Kubernetes Readiness Probe Hangs on /status Endpoint" href="/kb/kubernetes-readiness-probe-hangs-on-status" />

  <Card title="Large experiment downloads timeout in UI" href="/kb/large-experiment-downloads-timeout-in-ui" />

  <Card title="loadPrompt caching behavior in TypeScript SDK" href="/kb/loadprompt-caching-behavior-and-version-fallback" />

  <Card title="Log filtering with large user ID sets" href="/kb/log-filtering-with-large-user-id-sets" />

  <Card title="Log filtering with tags stalls after 50 results" href="/kb/log-filtering-with-tags-stalls-after-50-results" />

  <Card title="Logger and experiment span parent type mismatch error" href="/kb/logger-and-experiment-span-parent-type-mismatch-error" />

  <Card title="Logs not opening due to checksum instability" href="/kb/logs-not-opening-due-to-checksum-instability" />

  <Card title="Logs stopped after Brainstore platform update" href="/kb/logs-stopped-after-brainstore-platform-update" />

  <Card title="Loop models require Anthropic API key, not just Bedrock" href="/kb/loop-models-require-anthropic-api-key-not-just-bedrock" />

  <Card title="MCP returns empty logs for SaaS org from self-hosted endpoint" href="/kb/mcp-returns-empty-logs-for-saas-org-from-self-hosted-endpoint" />

  <Card title="Metadata filtering in custom views shows partial data" href="/kb/metadata-filtering-in-custom-views-shows" />

  <Card title="Missing classification values from automated scorer" href="/kb/missing-classification-values-from-automated-scorer" />

  <Card title="Missing scorers in automation rules editor" href="/kb/missing-scorers-in-automation-rules-editor" />

  <Card title="Model cost missing when using third-party SDKs" href="/kb/fireworks-cost-missing-when-using-vercel-ai-sdk" />

  <Card title="Moderation AutoEval missing from automation rules scorer picker" href="/kb/moderation-autoeval-missing-from-automation-rules-scorer-picker" />

  <Card title="Nested LLM call counting discrepancy" href="/kb/nested-llm-call-counting-discrepancy" />

  <Card title="No export-only permission in Braintrust ACL model" href="/kb/no-export-only-permission-in-braintrust-acl-model" />

  <Card title="Null input on spans when using OTEL attributes" href="/kb/null-input-on-spans-when-using-otel-attributes" />

  <Card title="Okta SAML tile login fails with missing RelayState" href="/kb/okta-saml-tile-login-fails-with-missing-relaystate" />

  <Card title="Online scorer deduplication with concurrent feedback" href="/kb/online-scorer-deduplication-with-concurrent-feedback" />

  <Card title="Online scorers not finding production traces" href="/kb/online-scorers-not-finding-production-traces-time-based-filter-issues-and-query-best-practices" />

  <Card title="Online scoring results not visible in UI" href="/kb/online-scoring-results-not-visible-in-ui-understanding-async-scoring-and-alert-timing" />

  <Card title="Online scoring rule failing after SDK update" href="/kb/online-scoring-rule-failing-after-sdk-update" />

  <Card title="Org-wide API key auditing is UI-only" href="/kb/org-wide-api-key-auditing-is-ui-only" />

  <Card title="OTEL metadata mapping and attachment rendering with PydanticAI" href="/kb/otel-metadata-mapping-and-attachment-rendering-with-pydanticai" />

  <Card title="OTLP traces endpoint payload limits" href="/kb/otlp-traces-endpoint-payload-limits" />

  <Card title="Playground gateway error despite valid API keys" href="/kb/playground-gateway-error-despite-valid-api-keys" />

  <Card title="Playground timeout with long-running model requests" href="/kb/playground-timeout-with-long-running-model" />

  <Card title="Populate project names in list prompts API" href="/kb/populate-project-names-in-list-prompts-api" />

  <Card title="Project Disappeared or Inaccessible: Data Recovery and" href="/kb/project-disappeared-or-inaccessible-data-recovery" />

  <Card title="Prompt shows None in experiment view" href="/kb/prompt-shows-none-in-experiment-view" />

  <Card title="PydanticAI integration counts wrapper spans as LLM calls" href="/kb/pydanticai-integration-counts-wrapper-spans-as" />

  <Card title="Query timeout requires timestamp filter" href="/kb/query-timeout-requires-timestamp-filter" />

  <Card title="Rate limit error during dataset iteration" href="/kb/rate-limit-error-during-dataset-iteration" />

  <Card title="Re-running scorers without re-running tasks" href="/kb/re-running-scorers-without-re-running-tasks" />

  <Card title="Recover or retrieve a deleted prompt" href="/kb/recover-or-retrieve-a-deleted-prompt" />

  <Card title="Recovering deleted experiment rows with versioned BTQL queries" href="/kb/recovering-deleted-experiment-rows" />

  <Card title="Remote eval dev mode fails with Pydantic parameters" href="/kb/remote-eval-dev-mode-fails-with-pydantic-parameters" />

  <Card title="Rows not attached to a dataset or experiment" href="/kb/dataset-not-linked-to-experiment-when-using-evalasync-with-parent" />

  <Card title="SAML login fails with email domain mismatch" href="/kb/saml-login-fails-with-email-domain-mismatch" />

  <Card title="Score logs by Topics facet values with batch scoring" href="/kb/facets-field-unavailable-in-automation-sql-filters" />

  <Card title="Scorer overwriting human review data with identical names" href="/kb/scorer-overwriting-human-review-data-with" />

  <Card title="Scorer pane columns collapse on open" href="/kb/scorer-pane-columns-collapse-on-open" />

  <Card title="Scores added via API not displaying in UI" href="/kb/scores-added-via-api-not-displaying-in-ui" />

  <Card title="SDK rate limits during dataset iteration" href="/kb/sdk-rate-limits-during-dataset-iteration" />

  <Card title="Search Timeout on Log Queries: CAST Operations in Custom" href="/kb/search-timeout-on-log-queries-cast" />

  <Card title="Securing remote eval endpoints: authentication and" href="/kb/securing-remote-eval-endpoints-authentication-and" />

  <Card title="Span Name Filtering Not Working on Monitoring Page:" href="/kb/span-name-filtering-not-working-on" />

  <Card title="SpanComponents encoding error when attaching feedback spans" href="/kb/spancomponents-encoding-error-when-attaching-feedback-spans" />

  <Card title="SQL queries timeout when missing timestamp filter" href="/kb/sql-queries-timeout-when-missing-timestamp-filter" />

  <Card title="SSL certificate verification failure behind corporate proxy" href="/kb/ssl-certificate-verification-failure-behind-corporate-proxy" />

  <Card title="SSO login fails with 'did not grant access' error" href="/kb/sso-login-fails-with-did-not-grant-access-error" />

  <Card title="Strict mode omits required field in structured output" href="/kb/strict-mode-omits-required-field-in-structured-output" />

  <Card title="Subquery alias conflicts with column names" href="/kb/unpivot-subquery-alias-conflicts-with-column-names" />

  <Card title="Tag filter dropdown missing tags from logged data" href="/kb/tag-filter-dropdown-missing-tags-from-logged-data" />

  <Card title="Temperature parameter error in prompt editor" href="/kb/temperature-parameter-error-in-prompt-editor" />

  <Card title="Temperature parameter included in GPT-5 prompts from SDK" href="/kb/temperature-parameter-included-in-gpt-5" />

  <Card title="Temperature parameter not supported in GPT-5 models" href="/kb/temperature-parameter-not-supported-in-gpt" />

  <Card title="Timestamps converted to UTC in traces" href="/kb/timestamps-converted-to-utc-in-traces" />

  <Card title="Topics facets empty due to Skipped status" href="/kb/topics-facets-empty-due-to-skipped-status" />

  <Card title="Trace gaps when exported span context is not persisted across restarts" href="/kb/trace-gaps-when-parent-span-export-is-not-persisted-across-restarts" />

  <Card title="Tracing Anthropic models via LiteLLM with Braintrust" href="/kb/tracing-anthropic-models-via-litellm-with-braintrust" />

  <Card title="Transient JSONL.GZ files in S3 export bucket" href="/kb/transient-jsonl-gz-files-in-s3-export-bucket" />

  <Card title="Trial quota limits and monthly reset cycle" href="/kb/trial-quota-limits-and-monthly-reset-cycle" />

  <Card title="Troubleshooting Organization Changes in Self-Hosted Data" href="/kb/troubleshooting-organization-changes-in-self-hosted" />

  <Card title="Troubleshooting Traces Stuck in Progress" href="/kb/troubleshooting-traces-stuck-in-progress" />

  <Card title="TypeScript SDK eval process hangs after completion" href="/kb/typescript-sdk-eval-process-hangs-after-completion-debugging-open-handles-and-resource-leaks" />

  <Card title="Understanding Brainstore query optimization warning logs" href="/kb/understanding-brainstore-query-optimization-warning-logs" />

  <Card title="Understanding traces vs spans in SQL & BTQL queries" href="/kb/understanding-traces-vs-spans-in-sql-btql-queries" />

  <Card title="Unexpected score columns in Logs" href="/kb/empty-automation-column-persists-after-scorer-deletion" />

  <Card title="wrapAISDK interleaved traces with concurrent calls" href="/kb/wrapaisdk-interleaved-traces-with-concurrent-calls" />
</CardGroup>

## 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).