AI agents

Enable AI Analyst and AI agents on a self-hosted Lightdash instance

Enterprise AI Analyst and AI agents need a valid LIGHTDASH_LICENSE_KEY set on your instance before any of the configuration below takes effect. See enterprise features for applying the key.

AI Analyst powers natural-language querying, AI-generated charts, and AI agents that answer questions in-app and in Slack. To enable it on a self-hosted instance you need a model provider and the AI Analyst feature flag. Every AI feature that runs on top — Data apps, AI writeback, Autopilot, MCP, and multi-agent Slack channels — assumes AI Analyst is enabled first.

Prerequisites

• Enterprise license — LIGHTDASH_LICENSE_KEY must be set on your instance.
• A model provider — OpenAI, Anthropic, Google Gemini, Google Vertex AI, Azure AI, OpenRouter, or AWS Bedrock. OpenAI and Anthropic are the most tested.
• Enough context budget on the chosen model — AI Analyst sends the project’s dbt catalog with every request.

Enable AI Analyst

Set the main switch and provide credentials for one provider — the minimal setup uses OpenAI, the default provider:

AI_COPILOT_ENABLED=true
OPENAI_API_KEY=<your-openai-api-key>

AI Analyst starts using the provider as soon as the backend restarts. To use a different provider, set AI_DEFAULT_PROVIDER (openai, anthropic, google, vertex, azure, openrouter, or bedrock) and the matching credentials — see model providers below. Optionally, set ASK_AI_BUTTON_ENABLED=true to add an “Ask AI” entry point in the app UI; without it, users reach agents from /ai-agents.

Model providers

Each provider’s exhaustive variable list lives in the environment variables reference; the notes below cover the choices and gotchas per provider.

OpenAI (default)

Leave AI_DEFAULT_PROVIDER unset or set it to openai, then set OPENAI_API_KEY. gpt-6-sol is the default model; override it with OPENAI_MODEL_NAME. All options: OpenAI configuration.

Behind an OpenAI-compatible LLM gateway (LiteLLM, an internal proxy), also set OPENAI_BASE_URL to the gateway URL and OPENAI_MODEL_NAME to a model your gateway exposes. If the gateway doesn’t support streaming (SSE), set OPENAI_SUPPORTS_STREAMING=false. If it enforces Zero Data Retention, set OPENAI_ZERO_DATA_RETENTION=true.

Anthropic

Set AI_DEFAULT_PROVIDER=anthropic and provide ANTHROPIC_API_KEY. claude-sonnet-5-5 is the default model; override it with ANTHROPIC_MODEL_NAME. All options: Anthropic configuration.

To send Anthropic traffic through a corporate gateway, add ANTHROPIC_BASE_URL. See Corporate LLM gateways for the required URL, authentication, and API paths.

Google Gemini

Set AI_DEFAULT_PROVIDER=google and GEMINI_API_KEY. The default model is gemini-3.8-flash; override it with GEMINI_MODEL_NAME. Use GEMINI_BASE_URL for a compatible gateway. All options: Google Gemini configuration.

Google Vertex AI

Set AI_DEFAULT_PROVIDER=vertex and either GOOGLE_VERTEX_API_KEY or GOOGLE_VERTEX_PROJECT with Application Default Credentials available to the backend and scheduler. The default location is global and model is gemini-3.8-flash; override the model with GOOGLE_VERTEX_MODEL_NAME. All options: Google Vertex AI configuration.

Azure AI

Set AI_DEFAULT_PROVIDER=azure and point Lightdash at your deployment with AZURE_AI_API_KEY, AZURE_AI_ENDPOINT, AZURE_AI_API_VERSION, and AZURE_AI_DEPLOYMENT_NAME. For reasoning-capable deployments (e.g. o3), also set AZURE_AI_DEPLOYMENT_SUPPORTS_REASONING=true. All options: Azure AI configuration.

OpenRouter

Set AI_DEFAULT_PROVIDER=openrouter and provide OPENROUTER_API_KEY; override the default model with OPENROUTER_MODEL_NAME. All options: OpenRouter configuration.

AWS Bedrock

Set AI_DEFAULT_PROVIDER=bedrock and BEDROCK_REGION (required — the AWS region where the target model is available), then authenticate with either BEDROCK_API_KEY or a BEDROCK_ACCESS_KEY_ID/BEDROCK_SECRET_ACCESS_KEY IAM pair — not both. Enable the corresponding models in the selected region before restarting Lightdash. All options: AWS Bedrock configuration.

To send Bedrock traffic through a corporate gateway, add BEDROCK_BASE_URL. The gateway must support the Bedrock APIs used by every enabled Lightdash consumer. See Corporate LLM gateways.

AI_DEFAULT_PROVIDER is instance-wide. Setting it to bedrock also routes the selected Data apps coding agent through Bedrock. APPS_CODING_AGENT chooses Claude or Codex; it does not change the provider.

Corporate LLM gateways

Lightdash can route AI Analyst, Autopilot, and Data app model traffic through an HTTP(S) corporate gateway. Use the base URL for the protocol your gateway exposes:

• OPENAI_BASE_URL for an OpenAI-compatible gateway.
• ANTHROPIC_BASE_URL for an Anthropic Messages gateway.
• BEDROCK_BASE_URL for a Bedrock-compatible gateway.

The gateway URL must include a scheme and must not contain credentials, query parameters, or a fragment. Each caller must be able to resolve and reach its configured gateway hostname.

Separate gateway routes for Data apps

If the backend and Data app sandboxes need different URLs to reach your LLM gateway, configure a sandbox-only base URL:

ANTHROPIC_BASE_URL=https://backend-gateway.example.com/anthropic
DATA_APPS_ANTHROPIC_BASE_URL=https://sandbox-gateway.example.com/anthropic

The Data app coding agent uses the DATA_APPS_ override when set and falls back to the shared provider URL when it is unset or empty. The same option is available for Bedrock and OpenAI; see the environment variable reference for all three variables. Anthropic URLs use the base before /v1; OpenAI URLs retain their API path, commonly /v1.

These overrides apply to instance-managed credentials only. Organizations using their own AI keys retain their resolved provider endpoints. Backend AI requests, AI writeback, and onboarding keep their existing routing. Provider selection and credentials stay unchanged; the sandbox URL must accept the existing coding agent’s authentication and API protocol. Provider *_CUSTOM_HEADERS are not forwarded to the coding agent.

Restart the Lightdash backend and scheduler workers after changing these environment variables. Check sandbox gateway egress, including the requirements for existing sandboxes.

Anthropic-compatible gateway

Configure ANTHROPIC_BASE_URL before the API’s /v1 segment. Lightdash accepts a trailing /v1 and removes it, but using the unversioned base avoids ambiguity:

AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=<gateway-bearer-token>
ANTHROPIC_BASE_URL=https://llm-gateway.example.com/anthropic

When ANTHROPIC_BASE_URL is set, Lightdash sends ANTHROPIC_API_KEY as an Authorization: Bearer token. Without a gateway, direct Anthropic requests continue to use the standard x-api-key header.

Lightdash queries /v1/models to determine which models the credential can access. If the gateway does not expose the Models API, set ANTHROPIC_AVAILABLE_MODELS to the exact comma-separated model names the gateway accepts.

An organization-level BYO Anthropic key cannot be combined with an instance-wide ANTHROPIC_BASE_URL. Remove the organization key to use the gateway, or remove the gateway URL to route that organization through its own Anthropic account.

Bedrock-compatible gateway

Configure the gateway together with the existing Bedrock provider settings:

AI_COPILOT_ENABLED=true
AI_DEFAULT_PROVIDER=bedrock
BEDROCK_REGION=us-east-1
BEDROCK_API_KEY=<gateway-bearer-token>
BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock

The backend Bedrock provider still requires one supported credential mode: BEDROCK_API_KEY, static AWS credentials, or BEDROCK_USE_DEFAULT_CREDENTIALS=true. A custom Bedrock gateway used by Codex requires BEDROCK_API_KEY; Codex cannot combine an overridden endpoint with IAM/SigV4 credentials.

For Claude Data apps, set CLAUDE_CODE_SKIP_BEDROCK_AUTH=true only when the gateway accepts Claude Code requests without AWS authentication. This setting suppresses credentials inside Claude Code; it does not remove the backend provider’s credential requirement.

Required gateway APIs

One base URL can serve multiple consumers only if the gateway implements every wire protocol those consumers use:

Consumer	Required path relative to the configured base
AI Analyst and Autopilot through Anthropic	Anthropic Messages: /v1/messages
Anthropic model discovery	Anthropic Models: /v1/models
AI Analyst and Autopilot through Bedrock	Bedrock Converse: /model/{model-id}/converse or /model/{model-id}/converse-stream
Bedrock verified-answer embeddings	Bedrock Invoke: /model/{model-id}/invoke
Claude Data apps through Anthropic	Anthropic Messages: /v1/messages
Claude Data apps through Bedrock	Bedrock Invoke: /model/{model-id}/invoke-with-response-stream
Codex Data apps through a Bedrock gateway	OpenAI Responses: /responses

A gateway that supports only Bedrock Converse, for example, can serve AI Analyst chat but cannot serve Claude Data app generation. For the coding-agent configuration and model naming rules, see Data apps.

These gateway settings do not reroute AI writeback or the onboarding agent. Autopilot uses the same provider configuration as AI Analyst. Its scheduler must also be able to reach the gateway.

Validate before rollout

1. Confirm the Lightdash backend and any scheduler running Autopilot can resolve and connect to the gateway hostname.
2. Open AI Analyst and send a short prompt with the configured model. If model discovery fails, verify /v1/models or set ANTHROPIC_AVAILABLE_MODELS.
3. If Data apps are enabled, generate a small app with each coding agent you plan to support. This verifies the sandbox’s separate network path and API wire.
4. If Autopilot is enabled, run it on a disposable project and check its recorded provider, model, and outcome. A successful configuration check does not prove the gateway accepts a model request.
5. Check gateway access logs for the expected paths in the table above. Redact authorization headers and tokens from logs.
6. Restrict direct provider egress only after all enabled consumers succeed through the gateway.

Verified answers

Verified answers use vector embeddings to match new questions to previously validated ones. Enable embeddings with AI_EMBEDDING_ENABLED=true and pick an embedding provider with AI_DEFAULT_EMBEDDING_PROVIDER (openai, bedrock, or azure). The embedding provider can differ from the chat provider — see verified answers for how they’re used at query time.

Autopilot

Autopilot runs scheduled maintenance for each enabled project using the AI SDK runtime. No runtime selector or separate Autopilot provider credentials are needed. It needs AI Analyst enabled and a provider configured through the instance model settings or organization AI providers and models. It uses the organization’s visible, available default model, then the configured provider default if available, then another available model. Azure uses its configured deployment directly. There is no per-project model override.

Every provider with credentials configured is available to AI Analyst and Autopilot, not only AI_DEFAULT_PROVIDER. Lightdash only calls a provider when the selected model belongs to it. To keep Autopilot on one provider, set the organization default model in Settings → Ask AI → General to one of that provider’s models. Use a provider’s *_AVAILABLE_MODELS variable to limit which of its models can be selected.

Enable the Autopilot feature on every API and scheduler process:

LIGHTDASH_ENABLE_FEATURE_FLAGS=ai-autopilot

Append ai-autopilot if the enable list already contains other flags, and remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present. Restart the API and scheduler after changing environment variables. Keep their provider and Autopilot configuration consistent; the scheduler executes scheduled runs and needs access to the selected provider or gateway.

A user with project management permissions can then enable Autopilot from the project’s Home page. Runs act as the user who enabled it and require that user to retain project management permissions. The AI SDK runtime needs no separate service-account token for Autopilot.

Setup and the activity page show the current provider, model, and key source. Enabling Autopilot checks that a model can be configured, without making a model request. Invalid credentials, unavailable deployments, and gateway errors can still fail the first run. Changing organization settings changes the next run’s selection; previous runs retain their recorded model.

Schedule and limits

Choose a schedule per project in the UI. MANAGED_AGENT_SCHEDULE supplies the fallback cron schedule, defaulting to 0 0 * * *. MANAGED_AGENT_SESSION_TIMEOUT_MS defaults to 600000 (10 minutes), and MANAGED_AGENT_MAX_STEPS defaults to 120 model steps per run. The deadline requests cancellation and prevents queued actions from starting; a content write already in progress must finish its bookkeeping. These limits do not set a dollar spending cap. See provider and usage.

Model qualification and cleanup

Autopilot only flags or deletes content on models that are qualified for it. Every other model runs in observe mode. When MANAGED_AGENT_VALIDATED_MODELS is unset, these models are qualified for cleanup:

Provider	Models
Anthropic	Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5
Amazon Bedrock	Claude Opus 5, Claude Opus 4.7, Claude Sonnet 5
OpenAI	GPT-5.6 Sol, GPT-5.5, GPT-5.4

The default models for OpenAI (gpt-6-sol) and Bedrock (claude-sonnet-4-5) are not qualified, so Autopilot runs in observe mode unless you choose a qualified model. Set the organization default model, or OPENAI_MODEL_NAME, ANTHROPIC_MODEL_NAME or BEDROCK_MODEL_NAME, to a model in the table.

On Anthropic, Autopilot switches to the newest of Claude Opus 5.5, 4.8 and 4.7 your organization may use, unless the organization default is already one of them. On Bedrock it does the same with Claude Opus 5.5 and 4.7. Other providers follow the organization default. Claude Opus 5.5 on Bedrock is not qualified, so a Bedrock organization that can use it runs in observe mode unless you qualify it in MANAGED_AGENT_VALIDATED_MODELS or leave it out of BEDROCK_AVAILABLE_MODELS.

Azure deployments, Google Gemini, Google Vertex AI, OpenRouter and any model not listed above start in observe mode. To qualify one, set MANAGED_AGENT_VALIDATED_MODELS to a JSON array of exact provider/model pairs with a mode of observe, flag, or cleanup. Setting the variable replaces the built-in list, so include the built-in models you still want; an empty value qualifies no model. Duplicate qualifications use the most restrictive mode; malformed configuration rejects startup. Qualify a model on disposable representative content before increasing its permissions; use the exact IDs shown in Autopilot, including Azure deployment names or Bedrock inference-profile prefixes.

Autopilot uses the more restrictive of the project’s requested cleanup mode and the model’s qualification. A downgrade appears in setup and the run summary. Observe mode does not mean read-only: chart creation and repair still follow the project’s capability toggles. Disable those capabilities as well when evaluating without content changes.

Upgrading from the hosted runtime

Lightdash 2.262.0 removed the hosted runtime. From that version Autopilot always runs on your configured AI provider.

• Nothing to change to keep Autopilot running. Provider credentials come from the shared AI configuration described above. Keep the schedule and timeout settings, and review the step limit and model qualifications.
• Remove the old settings. MANAGED_AGENT_RUNTIME, MANAGED_AGENT_ANTHROPIC_API_KEY, and MANAGED_AGENT_SKILL_IDS are retired and ignored. Compatibility warnings may appear at startup while these variables remain set.
• No configuration rollback. Setting MANAGED_AGENT_RUNTIME=anthropic-managed cannot restore the hosted runner. To roll back, redeploy a release before 2.262.0 with the credentials it needs.

On releases 2.255.0 to 2.261.x both runtimes exist and the AI SDK runner is the default. MANAGED_AGENT_RUNTIME selects the runner there and must match on the API and scheduler processes.

Agent identity

Beta Agent identity lets an organization admin choose who AI agents run as on Snowflake, BigQuery, Databricks, Athena, Postgres, Redshift, Trino and ClickHouse. It needs an Enterprise license: LIGHTDASH_LICENSE_KEY must be set on your instance.

1. Enable the feature flag

   Add agent-identity to LIGHTDASH_ENABLE_FEATURE_FLAGS on every backend/API replica and on any scheduler or worker process that executes AI agent jobs:

   LIGHTDASH_ENABLE_FEATURE_FLAGS=agent-identity
   

   Append agent-identity if the list already contains other flags, and remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present.

2. Restart

   Restart the affected processes. Lightdash reads these variables at startup.

The shared agent account on Snowflake, BigQuery, Databricks, Athena, Postgres, Redshift, Trino and ClickHouse needs no other instance setup. A project admin adds it on the Agent identity page of each project’s settings. See Snowflake, BigQuery, Databricks, Athena, Postgres, Redshift, Trino and ClickHouse.

Agent sign-in on Snowflake also needs the Snowflake agent integration. See Agent identity on Snowflake.

Lightdash checks that the identity that produced a saved result matches the reader. See Who can read a saved result. If this comparison causes a problem on your instance, set AGENT_RESULT_IDENTITY_CHECK_ENABLED=false to turn it off. The access checks stay on. See Agent identity variables.

Each agent query writes one structured info log line with the message Agent query before it runs in the warehouse. Set LIGHTDASH_LOG_FORMAT=JSON to keep the fields: queryUuid, projectUuid, warehouseConnectionUuid, userUuid, identity (marked_person, connected_person or ai_service_account), actorKind, principalKind, credentialUuid, identityUuid, principalRef and context. The line does not include the person’s email. See logging.

Agent identity audit entries and logs

Lightdash writes agent identity changes and failures to the application log. It does not store them in a table. Collect them from the log output of every backend/API replica and every scheduler or worker process.

Audit entries

Admin changes write an entry at the audit log level. The audit level is below info, so set LIGHTDASH_LOG_LEVEL=audit or LIGHTDASH_LOG_LEVEL=debug to write them. With the default level (http in production), Lightdash does not write audit entries.

Each entry has the actor who made the change, the action, the resource and the status. resource.metadata.event names the change:

resource.type	resource.metadata.event	action	Other resource.metadata fields
OrganizationAgentIdentityRule	agent_identity.rule_updated	update	warehouseType, previousSource, source
AiServiceAccount	agent_identity.service_account_saved	create for a new key, update for a replaced key	warehouseConnectionUuid, connectionName, previousGeneration, generation
AiServiceAccount	agent_identity.service_account_tested	test	warehouseConnectionUuid, connectionName, previousGeneration and generation (both the saved key), result (success or failure)
AiServiceAccount	agent_identity.service_account_deleted	delete	warehouseConnectionUuid, connectionName, previousGeneration

source and previousSource are marked_person (The person), agent_sign_in (The person’s agent sign-in) or ai_service_account (A shared agent account). resource.organizationUuid is on every entry, and resource.projectUuid is on shared agent account entries. A generation changes each time the key changes, so compare previousGeneration and generation to see that a key was replaced.

If your log indexer maps the actor field as text, set LIGHTDASH_LOG_AUDIT_ACTOR_AS_STRING=true.

Log lines

Lightdash also logs these events at the default levels:

Message	Level	Fields
Agent sign-in connect failed	warn	userUuid, organizationUuid, the failure reason, the redacted error
Agent sign-in disconnected	info	userUuid, organizationUuid
Agent sign-in refreshed	info	userUuid, organizationUuid
Agent sign-in refresh token rotated	info	userUuid, organizationUuid
Agent sign-in refresh failed	warn	userUuid, organizationUuid, the refusal reason, the redacted error
Agent result lineage refused	warn	queryUuid, the refused node, the reason. Depth and size refusals also have the limits.

BigQuery key refusals, Snowflake session check refusals and shared agent account test failures also log the redacted warehouse error. A status or diagnostic check that only reports a refusal logs at debug.

What Lightdash does not log

• Keys, tokens, client secrets and client emails are never in an audit entry or a log line.
• A logged warehouse error has errorClass, errorCode, errorCategory and a redacted errorMessage. Lightdash removes key blocks, quoted text and SQL from the message, and keeps only plain words and short numbers. errorCategory is a fixed value, for example invalid_grant, token_expired or permission_denied.
• No SQL or result data is logged in these entries.
• In access log URLs, Lightdash replaces the values of the OAuth code and state parameters with [REDACTED].

Agent identity on Snowflake

Agent sign-in lets Snowflake verify that a query comes from an agent session, so Snowflake policies can treat agents differently from people. Agents sign in through a separate Snowflake OAuth integration. The normal Sign in with Snowflake integration stays separate.

An organization admin sets up the integration in the app, with no instance setup. On Organization settings → Agents, they choose The person’s agent sign-in, run the SQL in Snowflake, and paste the account URL, client ID and client secret. See Set up the Snowflake agent integration. Lightdash encrypts the saved secret with LIGHTDASH_SECRET.

Each organization has one agent integration for one Snowflake account. A project on a second Snowflake account cannot complete the agent connection. Use the same account for the integration and the project connection.

The setup SQL in the app has the redirect URL of your instance: <siteHost>/api/v1/oauth/redirect/snowflake-ai, where <siteHost> is the scheme and host of SITE_URL. It always uses the host root, also when SITE_URL has a path. The sign-in requests the refresh_token scope, so keep OAUTH_ISSUE_REFRESH_TOKENS = TRUE on the integration.

An organization admin then selects Verify integration, and Turn on when the required checks pass. Lightdash does not save the agent sign-in rule while the organization has no saved client.

Lightdash refreshes each agent sign-in while the Snowflake grant lasts. OAUTH_REFRESH_TOKEN_VALIDITY sets the length of the grant, in seconds. When Snowflake rejects the OAuth client, people see “The warehouse OAuth client was rejected. Ask an administrator to check the agent sign-in settings.” Check that the integration is enabled and that the client saved on Organization settings → Agents matches it. See How long the agent connection lasts.

The agent-identity-silent-refresh feature flag controls the background refresh. It is on by default. To go back to the earlier behaviour, add it to LIGHTDASH_DISABLE_FEATURE_FLAGS and restart. The earlier behaviour asks people to connect again when the stored end date passes, and also after a temporary refresh failure.

The warehouse-oauth-refresh-lock feature flag makes Lightdash refresh each stored Snowflake or Databricks sign-in one at a time. On Snowflake, this covers agent sign-ins, personal Sign in with Snowflake connections and shared Snowflake sign-ins. On Databricks, it covers Sign in with Databricks and the other Databricks OAuth connections that store a refresh token. When two queries need a refresh at the same time, one refreshes and the other waits and uses the new token, so neither asks the person to sign in again. A connection test or save that refreshes a shared Snowflake sign-in also keeps the new token. The flag is on by default. To turn it off, add it to LIGHTDASH_DISABLE_FEATURE_FLAGS and restart.

To test over http://localhost, add OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE to the integration. This is for local development only. Do not set it in production.

Costs

Self-hosting AI Analyst means you pay the selected model provider directly. Every user question sends the project’s dbt catalog plus conversation history to the provider, so long conversations against large projects use noticeably more tokens than one-shot prompts. Query results also contribute to usage when data access is enabled. Provider dashboards expose usage — set spend limits before rolling out.

To keep prompts smaller:

• Limit each agent to the explores and fields it needs.
• Start a new thread when you change subjects so unrelated conversation history is not sent again.
• Keep always-included knowledge documents short.
• Enable compact filter expressions as described below.

Compact filter expressions

Compact filter expressions replace verbose structured filter schemas for AI agent and Model Context Protocol (MCP) query tools with a smaller expression syntax. This reduces the filter-related tool definitions and inputs sent to the model. Total savings vary by model, conversation history, caching, and tool usage; the setting does not reduce the catalog, existing conversation history, or query results.

Lightdash Cloud enables compact filter expressions automatically. On a self-hosted deployment, enable the feature on every backend/API replica and on any scheduler or worker process that executes AI agent jobs, then redeploy or recreate those containers:

LIGHTDASH_ENABLE_FEATURE_FLAGS=ai-filter-expressions

If LIGHTDASH_ENABLE_FEATURE_FLAGS already contains other flags, append ai-filter-expressions to its comma-separated list. Remove it from LIGHTDASH_DISABLE_FEATURE_FLAGS if present. Lightdash reads both variables at process startup.

Users do not need to create new agents or threads: the next response uses compact filter expressions, including in an existing thread. After enabling the feature for MCP, reconnect or refresh each client so it reloads the query tool definitions.

Permissions

AI Analyst follows the standard project role model: any user with query access to a project can use AI Analyst there. Restrict access at the project level via roles and groups. To limit AI Analyst to specific projects across the instance, set AI_COPILOT_ALLOWED_PROJECT_UUID to a comma-separated list of project UUIDs.

Troubleshooting

The “Ask AI” button doesn’t appear. Confirm AI_COPILOT_ENABLED=true, LIGHTDASH_LICENSE_KEY is set, and ASK_AI_BUTTON_ENABLED=true if you want the top-bar entry point. Users without query access to any project also won’t see it.

AI Analyst returns provider authentication errors. Check the API key for the selected AI_DEFAULT_PROVIDER. For Azure, verify AZURE_AI_ENDPOINT, AZURE_AI_API_VERSION, and AZURE_AI_DEPLOYMENT_NAME all match a deployment your key can call. For Bedrock, confirm the region has the target model enabled for your account.

Multi-step conversations fail against an OpenAI-compatible gateway. If the gateway enforces Zero Data Retention, set OPENAI_ZERO_DATA_RETENTION=true. If it doesn’t support SSE, set OPENAI_SUPPORTS_STREAMING=false.

Verified answers never match. Confirm AI_EMBEDDING_ENABLED=true and that the embedding provider credentials are set. Tune AI_VERIFIED_ANSWER_SIMILARITY_THRESHOLD if legitimate matches fall below the default 0.6 similarity cutoff.