What causes "Gemini API key must be provided to use agents." in Mintplex-Labs/anything-llm?

Create an API key at https://aistudio.google.com/app/apikey and set GEMINI_API_KEY in .env.

Mintplex-Labs/anything-llm · error · Error

Gemini API key must be provided to use agents.

Error message

Gemini API key must be provided to use agents.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:240) when the workspace agent provider is 'gemini' but GEMINI_API_KEY is unset/empty. Google Gemini (AI Studio / Generative Language API) authenticates with this single key, which is the only credential the guard validates.

Source

Thrown at server/utils/agents/index.js:241

          throw new Error("Z.AI API Key must be provided to use agents.");
        break;
      case "novita":
        if (!process.env.NOVITA_LLM_API_KEY)
          throw new Error("Novita API Key must be provided to use agents.");
        break;
      case "nvidia-nim":
        if (!process.env.NVIDIA_NIM_LLM_BASE_PATH)
          throw new Error(
            "NVIDIA NIM base path must be provided to use agents."
          );
        break;
      case "ppio":
        if (!process.env.PPIO_API_KEY)
          throw new Error("PPIO API Key must be provided to use agents.");
        break;
      case "gemini":
        if (!process.env.GEMINI_API_KEY)
          throw new Error("Gemini API key must be provided to use agents.");
        break;
      case "moonshotai":
        if (!process.env.MOONSHOT_AI_MODEL_PREF)
          throw new Error("Moonshot AI model must be set to use agents.");
        break;
      case "cometapi":
        if (!process.env.COMETAPI_LLM_API_KEY)
          throw new Error("CometAPI API Key must be provided to use agents.");
        break;
      case "foundry":
        if (!process.env.FOUNDRY_BASE_PATH)
          throw new Error("Foundry base path must be provided to use agents.");
        break;
      case "giteeai":
        if (!process.env.GITEE_AI_API_KEY)
          throw new Error("GiteeAI API Key must be provided to use agents.");
        break;
      case "cohere":

View on GitHub (pinned to 526360e320)

Solutions

Create an API key at https://aistudio.google.com/app/apikey and set GEMINI_API_KEY in .env.
Restart AnythingLLM to reload process.env.
Validate with curl 'https://generativelanguage.googleapis.com/v1/models?key=$GEMINI_API_KEY'.
Confirm the agent model is a valid Gemini model id (e.g. gemini-1.5-pro).

Example fix

// before (.env)
// GEMINI_API_KEY=

// after (.env)
GEMINI_API_KEY=AIza...your-key

Defensive patterns

Strategy: validation

Validate before calling

const key = process.env.GEMINI_API_KEY;
if (!key) {
  throw new Error(
    'Cannot start Gemini agent: set GEMINI_API_KEY (from aistudio.google.com/app/apikey) in .env.'
  );
}

Try / catch

try {
  await agentHandler.start();
} catch (e) {
  if (/Gemini API key must be provided/.test(e.message)) {
    return respondConfigError('gemini', ['GEMINI_API_KEY']);
  }
  throw e;
}

Prevention

Generate the key at aistudio.google.com and paste it into .env in one step.
Restart AnythingLLM to load the new env.
Add a CI/startup assertion that GEMINI_API_KEY is set when provider is gemini.
Keep .env out of version control; rotate keys in Google AI Studio on schedule.

When it happens

Trigger: An agent invocation runs with workspace.agentProvider === 'gemini' while GEMINI_API_KEY is absent from process.env. Path: #providerSetupAndCheck() -> checkSetup() at index.js:476.

Common situations: Gemini selected in System > LLM Preference without a key; key from aistudio.google.com not pasted into .env; .env edited but the server not restarted; key revoked/regenerated in Google AI Studio.

Related errors

AI-assisted analysis of Mintplex-Labs/anything-llm@526360e320 (2026-08-13). Data as JSON: /api/errors/f67fec47d3e74e17. Report an issue: GitHub.