Mintplex-Labs/anything-llm · error · Error

KoboldCPP must have a valid base path to use for the api.

Error message

KoboldCPP must have a valid base path to use for the api.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:161) when the workspace agent provider is 'koboldcpp' but KOBOLD_CPP_BASE_PATH is unset/empty. KoboldCPP is a self-hosted, OpenAI-compatible local server, so AnythingLLM only needs the base URL it exposes; there is no API key to validate. The guard fails fast so the agent does not attempt requests against an unknown host.

Source

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

          throw new Error("Ollama base path must be provided to use agents.");
        break;
      case "groq":
        if (!process.env.GROQ_API_KEY)
          throw new Error("Groq API key must be provided to use agents.");
        break;
      case "togetherai":
        if (!process.env.TOGETHER_AI_API_KEY)
          throw new Error("TogetherAI API key must be provided to use agents.");
        break;
      case "azure":
        if (!process.env.AZURE_OPENAI_ENDPOINT || !process.env.AZURE_OPENAI_KEY)
          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":

View on GitHub (pinned to 526360e320)

Solutions

  1. Set KOBOLD_CPP_BASE_PATH in .env to the running KoboldCPP server URL (default http://127.0.0.1:5000/v1).
  2. Restart AnythingLLM so process.env picks up the change.
  3. From the server host, curl the base path /models to confirm KoboldCPP is reachable.
  4. If KoboldCPP runs remotely, set the host to a LAN-reachable IP and ensure the port is open.

Example fix

// before (.env)
// KOBOLD_CPP_BASE_PATH=

// after (.env)
KOBOLD_CPP_BASE_PATH=http://127.0.0.1:5000/v1
Defensive patterns

Strategy: validation

Validate before calling

const base = process.env.KOBOLD_CPP_BASE_PATH;
if (!base) {
  throw new Error(
    'Cannot start KoboldCPP agent: set KOBOLD_CPP_BASE_PATH (e.g. http://127.0.0.1:5000/v1) in .env.'
  );
}
try { new URL(base); } catch { throw new Error('KOBOLD_CPP_BASE_PATH is not a valid URL'); }

Try / catch

try {
  await agentHandler.start();
} catch (e) {
  if (/KoboldCPP must have a valid base path/.test(e.message)) {
    return respondConfigError('koboldcpp', ['KOBOLD_CPP_BASE_PATH']);
  }
  throw e;
}

Prevention

When it happens

Trigger: An agent invocation runs with workspace.agentProvider === 'koboldcpp' while KOBOLD_CPP_BASE_PATH is absent from process.env. Reached via #providerSetupAndCheck() -> checkSetup() at index.js:476 before the aibitat session starts.

Common situations: KoboldCPP selected in System > LLM Preference on a fresh install without setting its URL; the .env has the variable but the value is empty/whitespace; server restarted from old env after switching provider in the UI; KoboldCPP running on another machine but the base path not updated to a reachable LAN address.

Related errors

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