What causes "Foundry base path must be provided to use agents." in Mintplex-Labs/anything-llm?

Set FOUNDRY_BASE_PATH to your Foundry endpoint in .env (e.g. FOUNDRY_BASE_PATH=http://foundry-host:5273/v1) and fully restart the server.

Mintplex-Labs/anything-llm · error · Error

Foundry base path must be provided to use agents.

Error message

Foundry base path must be provided to use agents.

What it means

Thrown by AgentHandlerContext.checkSetup() (server/utils/agents/index.js:128) when the resolved agent provider is 'foundry' but process.env.FOUNDRY_BASE_PATH is unset/empty. checkSetup() is a precondition gate executed during agent.init() -> #providerSetupAndCheck() before any AI provider client is constructed, so every agent turn (workspace agent, @agent mentions, skills) fails fast until the env var exists.

Source

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

      case "ppio":
        if (!process.env.PPIO_API_KEY)
          throw new Error("PPIO API Key must be provided to use agents.");
        break;
      case "gemini":
        if (!process.env.GEMINI_API_KEY)
          throw new Error("Gemini API key must be provided to use agents.");
        break;
      case "moonshotai":
        if (!process.env.MOONSHOT_AI_MODEL_PREF)
          throw new Error("Moonshot AI model must be set to use agents.");
        break;
      case "cometapi":
        if (!process.env.COMETAPI_LLM_API_KEY)
          throw new Error("CometAPI API Key must be provided to use agents.");
        break;
      case "foundry":
        if (!process.env.FOUNDRY_BASE_PATH)
          throw new Error("Foundry base path must be provided to use agents.");
        break;
      case "giteeai":
        if (!process.env.GITEE_AI_API_KEY)
          throw new Error("GiteeAI API Key must be provided to use agents.");
        break;
      case "cohere":
        if (!process.env.COHERE_API_KEY)
          throw new Error("Cohere API key must be provided to use agents.");
        break;
      case "docker-model-runner":
        if (!process.env.DOCKER_MODEL_RUNNER_BASE_PATH)
          throw new Error(
            "Docker Model Runner base path must be provided to use agents."
          );
        break;
      case "privatemode":
        if (!process.env.PRIVATEMODE_LLM_BASE_PATH)
          throw new Error(

View on GitHub (pinned to 526360e320)

Solutions

Set FOUNDRY_BASE_PATH to your Foundry endpoint in .env (e.g. FOUNDRY_BASE_PATH=http://foundry-host:5273/v1) and fully restart the server.
If already set, confirm the running process loaded it (log process.env.FOUNDRY_BASE_PATH at boot) - containers often need a recreate, not a restart.
If Foundry is not intended, switch the workspace Agent Provider in the UI or unset LLM_PROVIDER so it no longer falls back to foundry.

Example fix

// before (.env)
FOUNDRY_BASE_PATH=
LLM_PROVIDER=foundry
// after (.env)
FOUNDRY_BASE_PATH=http://foundry-host:5273/v1
LLM_PROVIDER=foundry

Defensive patterns

Strategy: validation

Validate before calling

function assertFoundryReady(workspaceAgentProvider) {
  const usingFoundry = workspaceAgentProvider === 'foundry' || process.env.LLM_PROVIDER === 'foundry';
  if (usingFoundry && !process.env.FOUNDRY_BASE_PATH)
    throw new Error('FOUNDRY_BASE_PATH missing - set it before starting an agent.');
}

Try / catch

try { await agent.init(); } catch (e) { if (/Foundry base path must be provided/.test(e.message)) return showProviderConfig('foundry'); throw e; }

Prevention

Validate required provider env vars at server boot and fail loudly if a configured provider lacks its credential.
Restart the server after every .env change.
Maintain a startup self-check mapping each provider id to its required env var.

When it happens

Trigger: A chat turn calls agent.init(); this.provider resolves to 'foundry' (from workspace.agentProvider or system LLM_PROVIDER fallback); the switch reaches case 'foundry' and process.env.FOUNDRY_BASE_PATH is falsy.

Common situations: Foundry selected in Workspace Settings -> Agent Provider but the base path was never saved; .env edited but the server/container not restarted; Docker/k8s run dropped -e FOUNDRY_BASE_PATH; config copied from a deployment that used a different provider.

Related errors

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