Budibase/budibase · critical · HTTPError

Budibase AI is not configured in this environment (BBAI_LITE

Error message

Budibase AI is not configured in this environment (BBAI_LITELLM_KEY is missing). Ensure the key is available to every service that runs agents, including the automation worker.

What it means

Thrown by getBBAIKey when the BBAI_LITELLM_KEY environment variable is unset or empty. Budibase AI's OpenAI client resolves its key lazily, so without this up-front check the failure would surface later as a misleading "OpenAI API key is missing" error. It is an HTTPError with status 500.

Source

Thrown at packages/server/src/sdk/workspace/ai/llm/bbai.ts:28

  LLMResponse,
  ReasoningEffort,
} from "@budibase/types"
import tracer from "dd-trace"
import { licensing, quotas } from "@budibase/pro"
import { wrapLanguageModel } from "ai"
import { TransformStream } from "node:stream/web"
import environment from "../../../../environment"
import { Readable } from "stream"
import { blob } from "stream/consumers"
import { unwrapLiteLLMFileId } from "./litellm"

// The OpenAI client resolves its API key lazily, so an undefined key would
// otherwise surface later as a misleading "OpenAI API key is missing" error.
// Validate up front so a missing key fails with an explicit message.
export function getBBAIKey(): string {
  const apiKey = environment.BBAI_LITELLM_KEY
  if (!apiKey) {
    throw new HTTPError(
      "Budibase AI is not configured in this environment (BBAI_LITELLM_KEY is missing). " +
        "Ensure the key is available to every service that runs agents, including the automation worker.",
      500
    )
  }
  return apiKey
}

interface OpenAIUsage {
  prompt_tokens?: number
  completion_tokens?: number
  input_tokens?: number
  output_tokens?: number
}

const calculateBudibaseAICredits = (
  inputTokens: number,
  outputTokens: number

View on GitHub (pinned to a81a902e9a)

Solutions

Set BBAI_LITELLM_KEY in the environment of every service that runs agents (server AND automation worker)
Restart the server and worker processes so the new env var is picked up
If using docker-compose/Kubernetes, add the variable to each backend service's env configuration

Example fix

// before: worker env missing key
services:
  worker:
    environment:
      - LITELLM_URL=...
// after
services:
  worker:
    environment:
      - BBAI_LITELLM_KEY=${BBAI_LITELLM_KEY}
      - LITELLM_URL=...

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.BBAI_LITELLM_KEY) {
  throw new Error("BBAI_LITELLM_KEY must be set before starting agents")
}

Try / catch

try {
  await runAgent(input)
} catch (e) {
  if (e.message.includes("BBAI_LITELLM_KEY is missing")) {
    return { error: "Budibase AI is not configured in this environment" }
  }
  throw e
}

Prevention

Add BBAI_LITELLM_KEY to server AND worker env files/docker-compose services
Add a startup health check that fails fast when the key is absent
Document the variable in deployment runbooks for self-hosted installs

When it happens

Trigger: Any Budibase AI agent/LLM call (chat, automation agent, reviewer) when environment.BBAI_LITELLM_KEY is not set in the process running the agent — server or worker.

Common situations: Self-hosted deployments where the key was added to the server .env but not the worker's env; docker-compose files missing the env passthrough; upgrades that introduced Budibase AI without updating env config.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/a4adff76004d46c0. Report an issue: GitHub.