Budibase/budibase · error · HTTPError

Gemini File Search failed. Set GEMINI_API_KEY on your local

Error message

Gemini File Search failed. Set GEMINI_API_KEY on your local environment

What it means

getGeminiApiKey reads environment.GEMINI_API_KEY and throws HTTPError 400 when it is missing or empty. Gemini File Search for knowledge bases requires this key to authenticate against Gemini via LiteLLM.

Source

Thrown at packages/server/src/sdk/workspace/ai/knowledgeBase/geminiFileStore.ts:75

interface RagSearchResponse {
  data?: RagSearchResultItem[]
}

interface GeminiFileStoreResponse {
  ok: boolean
  status: number
}

const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504])
const RETRY_DELAYS_MS = [500, 1500, 3000]

export const isGeminiFileSearchConfigured = () =>
  !!environment.GEMINI_API_KEY?.trim()

export const getGeminiApiKey = () => {
  const key = environment.GEMINI_API_KEY?.trim()
  if (!key) {
    throw new HTTPError(
      "Gemini File Search failed. Set GEMINI_API_KEY on your local environment",
      400
    )
  }
  return key
}

const isRetryableResponse = (response: GeminiFileStoreResponse) => {
  return !response.ok && RETRYABLE_STATUS_CODES.has(response.status)
}

const isRetryableFetchError = (error: unknown) => {
  return error instanceof Error && error.name === "FetchError"
}

const requestWithRetries = async <TResponse extends GeminiFileStoreResponse>(
  request: () => Promise<TResponse>
): Promise<TResponse> => {

View on GitHub (pinned to a81a902e9a)

Solutions

1. Set GEMINI_API_KEY=<valid key> in the server's environment (.env) and restart the server
2. Verify with isGeminiFileSearchConfigured() before attempting Gemini knowledge base operations
3. Check the key is present in the same process that runs packages/server, not only worker or builder

Example fix

// before (.env)
# GEMINI_API_KEY not set
// after (.env)
GEMINI_API_KEY=AIza...
# then restart the server process

import { isGeminiFileSearchConfigured } from "./geminiFileStore"
if (!isGeminiFileSearchConfigured()) {
  throw new Error("GEMINI_API_KEY is not configured")
}

try {
  await ingestGeminiFile({ ... })
} catch (e) {
  if (e instanceof HTTPError && e.status === 400 && /GEMINI_API_KEY/.test(e.message)) {
    // surface a configuration hint to the operator
  }
}

When it happens

Trigger: Any Gemini file-store operation (createGeminiFileStore, deleteGeminiVectorStore, ingestGeminiFile, searchGeminiFileStore) invoked when GEMINI_API_KEY is unset, empty, or whitespace-only in the server environment.

Common situations: Local/self-hosted dev environment where GEMINI_API_KEY was never added to .env; key defined only in the builder/worker env but not the server process; server not restarted after adding the key; key accidentally set to blank after a deploy.

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

• Budibase AI is not configured in this environment (BBAI_LITE
• No Budibase URL found
• Workspace DB not found - self-host users using cloud don't h
• CouchDB username not set
• CouchDB password not set

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