Mintplex-Labs/anything-llm · error · Error

Azure OpenAI API endpoint and key must be provided to use ag

Error message

Azure OpenAI API endpoint and key must be provided to use agents.

What it means

Thrown by AgentHandler.checkSetup() (server/utils/agents/index.js:155) when the workspace's configured agent provider is 'azure' but either AZURE_OPENAI_ENDPOINT or AZURE_OPENAI_KEY is unset/empty in the server process. It is a synchronous, pre-flight config guard that fires before any model call so the agent fails fast instead of mid-stream against Azure OpenAI. Azure uniquely requires BOTH an endpoint URL and a key because the Azure OpenAI resource is addressed per-deployment rather than via a global host.

Source

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

      case "lmstudio":
        if (!process.env.LMSTUDIO_BASE_PATH)
          throw new Error("LMStudio base path must be provided to use agents.");
        break;
      case "ollama":
        if (!process.env.OLLAMA_BASE_PATH)
          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.");

View on GitHub (pinned to 526360e320)

Solutions

1. In the AnythingLLM .env set both AZURE_OPENAI_ENDPOINT (e.g. https://my-aoai.openai.azure.com) and AZURE_OPENAI_KEY (from the Azure portal > your Azure OpenAI resource > Keys and Endpoint).
2. Restart the server / recreate the Docker container so process.env is reloaded (AnythingLLM reads .env at process start).
3. Confirm in System > LLM Preference > Azure OpenAI that the connection test passes and a deployment model is chosen.
4. Verify the deployment name referenced by the agent's model actually exists on that Azure resource.

Example fix

// before (.env)
// AZURE_OPENAI_ENDPOINT=
// AZURE_OPENAI_KEY=

// after (.env)
AZURE_OPENAI_ENDPOINT=https://my-aoai.openai.azure.com
AZURE_OPENAI_KEY=1a2b3c...your-deployment-key

// Run before starting an agent whose provider is 'azure'
const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
const key = process.env.AZURE_OPENAI_KEY;
if (!endpoint || !key) {
  throw new Error(
    'Cannot start Azure agent: set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_KEY in .env, then restart AnythingLLM.'
  );
}
// safe to proceed: new AgentHandler({ uuid }).start()

try {
  await agentHandler.start(); // calls #providerSetupAndCheck -> checkSetup
} catch (e) {
  if (/Azure OpenAI API endpoint and key/.test(e.message)) {
    // surface a config-fixable error to the user, do not retry
    return respondConfigError('azure', ['AZURE_OPENAI_ENDPOINT', 'AZURE_OPENAI_KEY']);
  }
  throw e; // unknown failure, rethrow
}

When it happens

Trigger: An agent run starts (@agent mention, or chat mode 'automatic' with a workspace whose agentProvider === 'azure') while AZURE_OPENAI_ENDPOINT or AZURE_OPENAI_KEY is missing from process.env. The call path is #providerSetupAndCheck() -> this.checkSetup() at index.js:476, which throws before the aibitat session is built.

Common situations: Fresh AnythingLLM deploy where the Azure provider was selected in System > LLM Preference but the .env was never populated; .env edited but the Node server / Docker container not restarted; endpoint set but key left blank (or vice-versa); AZURE_OPENAI_ENDPOINT given without the https://<resource>.openai.azure.com scheme; running under Docker without --env-file=.env so the host env never reaches the container.

Related errors

• KoboldCPP must have a valid base path to use for the api.
• LocalAI must have a valid base path to use for the api.
• OpenRouter API key must be provided to use agents.
• Mistral API key must be provided to use agents.
• API base path must be provided to use agents.

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