{"record":{"id":"a227a1f029cdee25","repo":"Mintplex-Labs/anything-llm","slug":"azure-openai-api-endpoint-and-key-must-be-provided","errorCode":null,"errorMessage":"Azure OpenAI API endpoint and key must be provided to use agents.","messagePattern":"Azure OpenAI API endpoint and key must be provided to use agents\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/utils/agents/index.js","lineNumber":156,"sourceCode":"      case \"lmstudio\":\n        if (!process.env.LMSTUDIO_BASE_PATH)\n          throw new Error(\"LMStudio base path must be provided to use agents.\");\n        break;\n      case \"ollama\":\n        if (!process.env.OLLAMA_BASE_PATH)\n          throw new Error(\"Ollama base path must be provided to use agents.\");\n        break;\n      case \"groq\":\n        if (!process.env.GROQ_API_KEY)\n          throw new Error(\"Groq API key must be provided to use agents.\");\n        break;\n      case \"togetherai\":\n        if (!process.env.TOGETHER_AI_API_KEY)\n          throw new Error(\"TogetherAI API key must be provided to use agents.\");\n        break;\n      case \"azure\":\n        if (!process.env.AZURE_OPENAI_ENDPOINT || !process.env.AZURE_OPENAI_KEY)\n          throw new Error(\n            \"Azure OpenAI API endpoint and key must be provided to use agents.\"\n          );\n        break;\n      case \"koboldcpp\":\n        if (!process.env.KOBOLD_CPP_BASE_PATH)\n          throw new Error(\n            \"KoboldCPP must have a valid base path to use for the api.\"\n          );\n        break;\n      case \"localai\":\n        if (!process.env.LOCAL_AI_BASE_PATH)\n          throw new Error(\n            \"LocalAI must have a valid base path to use for the api.\"\n          );\n        break;\n      case \"openrouter\":\n        if (!process.env.OPENROUTER_API_KEY)\n          throw new Error(\"OpenRouter API key must be provided to use agents.\");","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/526360e320da9d1b36074be5ed64fe76e5bbfbbd/server/utils/agents/index.js#L138-L174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Restart the server / recreate the Docker container so process.env is reloaded (AnythingLLM reads .env at process start).","Confirm in System > LLM Preference > Azure OpenAI that the connection test passes and a deployment model is chosen.","Verify the deployment name referenced by the agent's model actually exists on that Azure resource."],"exampleFix":"// before (.env)\n// AZURE_OPENAI_ENDPOINT=\n// AZURE_OPENAI_KEY=\n\n// after (.env)\nAZURE_OPENAI_ENDPOINT=https://my-aoai.openai.azure.com\nAZURE_OPENAI_KEY=1a2b3c...your-deployment-key","handlingStrategy":"validation","validationCode":"// Run before starting an agent whose provider is 'azure'\nconst endpoint = process.env.AZURE_OPENAI_ENDPOINT;\nconst key = process.env.AZURE_OPENAI_KEY;\nif (!endpoint || !key) {\n  throw new Error(\n    'Cannot start Azure agent: set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_KEY in .env, then restart AnythingLLM.'\n  );\n}\n// safe to proceed: new AgentHandler({ uuid }).start()","typeGuard":null,"tryCatchPattern":"try {\n  await agentHandler.start(); // calls #providerSetupAndCheck -> checkSetup\n} catch (e) {\n  if (/Azure OpenAI API endpoint and key/.test(e.message)) {\n    // surface a config-fixable error to the user, do not retry\n    return respondConfigError('azure', ['AZURE_OPENAI_ENDPOINT', 'AZURE_OPENAI_KEY']);\n  }\n  throw e; // unknown failure, rethrow\n}","preventionTips":["Always set both AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_KEY together; the guard ORs them so either missing triggers it.","Restart AnythingLLM (or recreate the container with --env-file) after every .env change.","Add a startup self-check that fails the boot if any provider the DB references lacks its env vars.","Keep .env out of git; rotate keys in the Azure portal then update .env on the same host."],"tags":["agents","llm-provider","azure","openai","environment-variables","config"],"backgroundTag":null,"analyzedSha":"526360e320da9d1b36074be5ed64fe76e5bbfbbd","analyzedAt":"2026-08-13T01:45:47.170Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}