Mintplex-Labs/anything-llm · error · Error

API base path must be provided to use agents.

Error message

API base path must be provided to use agents.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:181) when the workspace agent provider is 'generic-openai' but GENERIC_OPEN_AI_BASE_PATH is unset/empty. The generic-openai provider points AnythingLLM at any OpenAI-compatible endpoint, so the base URL is the only required credential and is what this guard checks.

Source

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

          );
        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."
          );
        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."

View on GitHub (pinned to 526360e320)

Solutions

  1. Set GENERIC_OPEN_AI_BASE_PATH in .env to the OpenAI-compatible endpoint (usually ending in /v1).
  2. Restart AnythingLLM so process.env reloads.
  3. If the endpoint needs auth, also set GENERIC_OPEN_AI_API_KEY (the base-path guard only checks the URL).
  4. Confirm the endpoint answers with curl <base path>/models.

Example fix

// before (.env)
// GENERIC_OPEN_AI_BASE_PATH=

// after (.env)
GENERIC_OPEN_AI_BASE_PATH=https://my-internal-gateway.example.com/v1
Defensive patterns

Strategy: validation

Validate before calling

const base = process.env.GENERIC_OPEN_AI_BASE_PATH;
if (!base) {
  throw new Error(
    'Cannot start generic-openai agent: set GENERIC_OPEN_AI_BASE_PATH (OpenAI-compatible URL, usually ending in /v1) in .env.'
  );
}
try { new URL(base); } catch { throw new Error('GENERIC_OPEN_AI_BASE_PATH is not a valid URL'); }

Try / catch

try {
  await agentHandler.start();
} catch (e) {
  if (/API base path must be provided/.test(e.message)) {
    return respondConfigError('generic-openai', ['GENERIC_OPEN_AI_BASE_PATH']);
  }
  throw e;
}

Prevention

When it happens

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

Common situations: Generic OpenAI provider selected in System > LLM Preference but the custom endpoint URL was never entered; the base path was set in the UI but not persisted to .env; pointing at a gateway (vLLM, OpenLLM, internal proxy) whose URL changed; missing /v1 suffix causing later failures even after this guard passes.

Related errors

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