Mintplex-Labs/anything-llm · error · Error

Perplexity API key must be provided to use agents.

Error message

Perplexity API key must be provided to use agents.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:185) when the workspace agent provider is 'perplexity' but PERPLEXITY_API_KEY is unset/empty. Perplexity's online-API (Sonar models) requires this key, which is the only value the guard validates.

Source

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

          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."
          );
        break;
      case "bedrock":
        // No validations since there are many possible authentication methods
        break;
      case "fireworksai":
        if (!process.env.FIREWORKS_AI_LLM_API_KEY)
          throw new Error(
            "FireworksAI API Key must be provided to use agents."
          );
        break;
      case "deepseek":
        if (!process.env.DEEPSEEK_API_KEY)

View on GitHub (pinned to 526360e320)

Solutions

  1. Generate a key at https://www.perplexity.ai/settings/api and set PERPLEXITY_API_KEY in .env.
  2. Restart AnythingLLM to reload process.env.
  3. Verify with curl -H 'Authorization: Bearer $PERPLEXITY_API_KEY' https://api.perplexity.ai/chat/completions.
  4. Make sure the agent's chosen model is a Perplexity online model (e.g. sonar).

Example fix

// before (.env)
// PERPLEXITY_API_KEY=

// after (.env)
PERPLEXITY_API_KEY=pplx-...your-key
Defensive patterns

Strategy: validation

Validate before calling

const key = process.env.PERPLEXITY_API_KEY;
if (!key || !key.startsWith('pplx-')) {
  throw new Error(
    'Cannot start Perplexity agent: set PERPLEXITY_API_KEY (from perplexity.ai/settings/api) in .env.'
  );
}

Try / catch

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

Prevention

When it happens

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

Common situations: Perplexity selected in System > LLM Preference on a fresh install with no key; key created at perplexity.ai/settings/api but not added to .env; .env updated but the server not restarted; key invalidated after plan change.

Related errors

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