What causes "LocalAI must have a valid base path to use for the api." in Mintplex-Labs/anything-llm?

Set LOCAL_AI_BASE_PATH in .env to the LocalAI server URL (e.g. http://127.0.0.1:8080/v1).

Mintplex-Labs/anything-llm · error · Error

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

Error message

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

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:167) when the workspace agent provider is 'localai' but LOCAL_AI_BASE_PATH is unset/empty. LocalAI is a self-hosted OpenAI-drop-in replacement, so only its base URL is required and validated. The guard prevents the agent from running with no target endpoint.

Source

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

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

View on GitHub (pinned to 526360e320)

Solutions

Set LOCAL_AI_BASE_PATH in .env to the LocalAI server URL (e.g. http://127.0.0.1:8080/v1).
Restart AnythingLLM to reload process.env.
Verify reachability with curl <base path>/v1/models from the AnythingLLM host.
When LocalAI runs in another container, use the docker network hostname/IP instead of 127.0.0.1.

Example fix

// before (.env)
// LOCAL_AI_BASE_PATH=

// after (.env)
LOCAL_AI_BASE_PATH=http://127.0.0.1:8080/v1

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Verify the LocalAI server answers /v1/models from the AnythingLLM host before configuring it.
Use the docker network hostname, not localhost, when LocalAI runs in another container.
Restart AnythingLLM after each .env change.
Add a startup self-check that lists all configured providers and their required env vars.

When it happens

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

Common situations: LocalAI picked in System > LLM Preference on a fresh install with no URL set; .env edited but server not restarted; base path left pointing at http://localhost:8080 while LocalAI actually runs in a separate Docker network where 'localhost' is the wrong host.

Related errors

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