{"record":{"id":"dff4d876108812b6","repo":"Mintplex-Labs/anything-llm","slug":"koboldcpp-must-have-a-valid-base-path-to-use-for-t-dff4d8","errorCode":null,"errorMessage":"KoboldCPP must have a valid base path to use for the api.","messagePattern":"KoboldCPP must have a valid base path to use for the api\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/utils/agents/index.js","lineNumber":162,"sourceCode":"          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.\");\n        break;\n      case \"mistral\":\n        if (!process.env.MISTRAL_API_KEY)\n          throw new Error(\"Mistral API key must be provided to use agents.\");\n        break;\n      case \"generic-openai\":","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/526360e320da9d1b36074be5ed64fe76e5bbfbbd/server/utils/agents/index.js#L144-L180","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set KOBOLD_CPP_BASE_PATH in .env to the running KoboldCPP server URL (default http://127.0.0.1:5000/v1).","Restart AnythingLLM so process.env picks up the change.","From the server host, curl the base path /models to confirm KoboldCPP is reachable.","If KoboldCPP runs remotely, set the host to a LAN-reachable IP and ensure the port is open."],"exampleFix":"// before (.env)\n// KOBOLD_CPP_BASE_PATH=\n\n// after (.env)\nKOBOLD_CPP_BASE_PATH=http://127.0.0.1:5000/v1","handlingStrategy":"validation","validationCode":"const base = process.env.KOBOLD_CPP_BASE_PATH;\nif (!base) {\n  throw new Error(\n    'Cannot start KoboldCPP agent: set KOBOLD_CPP_BASE_PATH (e.g. http://127.0.0.1:5000/v1) in .env.'\n  );\n}\ntry { new URL(base); } catch { throw new Error('KOBOLD_CPP_BASE_PATH is not a valid URL'); }","typeGuard":null,"tryCatchPattern":"try {\n  await agentHandler.start();\n} catch (e) {\n  if (/KoboldCPP must have a valid base path/.test(e.message)) {\n    return respondConfigError('koboldcpp', ['KOBOLD_CPP_BASE_PATH']);\n  }\n  throw e;\n}","preventionTips":["Confirm the KoboldCPP server is running and reachable before selecting it as the agent provider.","When AnythingLLM is containerized, point KOBOLD_CPP_BASE_PATH at a host/docker-network address, not 127.0.0.1.","Restart AnythingLLM after editing .env so process.env reloads.","Add a boot-time reachability probe for local-LLM base paths."],"tags":["agents","llm-provider","koboldcpp","local-llm","environment-variables","config"],"backgroundTag":null,"analyzedSha":"526360e320da9d1b36074be5ed64fe76e5bbfbbd","analyzedAt":"2026-08-13T01:45:47.170Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}