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

Create a key at https://openrouter.ai/keys and set OPENROUTER_API_KEY in .env.

Mintplex-Labs/anything-llm · error · Error

OpenRouter API key must be provided to use agents.

Error message

OpenRouter API key must be provided to use agents.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:173) when the workspace agent provider is 'openrouter' but OPENROUTER_API_KEY is unset/empty. OpenRouter is a hosted gateway to many models behind a single key, so AnythingLLM validates only that key. The guard fires before the agent session so an unauthenticated call never leaves the server.

Source

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

          throw new Error(
            "Azure OpenAI API endpoint and key must be provided to use agents."
          );
        break;
      case "koboldcpp":
        if (!process.env.KOBOLD_CPP_BASE_PATH)
          throw new Error(
            "KoboldCPP must have a valid base path to use for the api."
          );
        break;
      case "localai":
        if (!process.env.LOCAL_AI_BASE_PATH)
          throw new Error(
            "LocalAI must have a valid base path to use for the api."
          );
        break;
      case "openrouter":
        if (!process.env.OPENROUTER_API_KEY)
          throw new Error("OpenRouter API key must be provided to use agents.");
        break;
      case "mistral":
        if (!process.env.MISTRAL_API_KEY)
          throw new Error("Mistral API key must be provided to use agents.");
        break;
      case "generic-openai":
        if (!process.env.GENERIC_OPEN_AI_BASE_PATH)
          throw new Error("API base path must be provided to use agents.");
        break;
      case "perplexity":
        if (!process.env.PERPLEXITY_API_KEY)
          throw new Error("Perplexity API key must be provided to use agents.");
        break;
      case "textgenwebui":
        if (!process.env.TEXT_GEN_WEB_UI_BASE_PATH)
          throw new Error(
            "TextWebGenUI API base path must be provided to use agents."
          );

View on GitHub (pinned to 526360e320)

Solutions

Create a key at https://openrouter.ai/keys and set OPENROUTER_API_KEY in .env.
Restart AnythingLLM so process.env reloads the key.
Confirm the key works with: curl -H 'Authorization: Bearer $OPENROUTER_API_KEY' https://openrouter.ai/api/v1/models.
Re-run the agent; the connection test in System > LLM Preference should now pass.

Example fix

// before (.env)
// OPENROUTER_API_KEY=

// after (.env)
OPENROUTER_API_KEY=sk-or-v1-...your-key

Defensive patterns

Strategy: validation

Validate before calling

const key = process.env.OPENROUTER_API_KEY;
if (!key || !key.startsWith('sk-or-')) {
  throw new Error(
    'Cannot start OpenRouter agent: set OPENROUTER_API_KEY (from openrouter.ai/keys) in .env.'
  );
}

Try / catch

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

Prevention

Store keys in a secret manager; load them into .env at deploy, never commit .env.
Restart AnythingLLM after updating OPENROUTER_API_KEY.
Add a CI check that asserts required env vars are non-empty for the configured provider.
Rotate keys at openrouter.ai/keys and update .env on the same host to avoid stale values.

When it happens

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

Common situations: OpenRouter selected in System > LLM Preference without pasting a key; key revoked/deleted at openrouter.ai/keys but .env still holds the old (now empty) line; .env present but the Docker container was started without --env-file; trailing whitespace or quotes in the value stripped incorrectly.

Related errors

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