{"record":{"id":"06768bc7643dcdbb","repo":"Mintplex-Labs/anything-llm","slug":"koboldcpp-must-have-a-valid-model-set","errorCode":null,"errorMessage":"KoboldCPP must have a valid model set.","messagePattern":"KoboldCPP must have a valid model set\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"server/utils/AiProviders/koboldCPP/index.js","lineNumber":27,"sourceCode":"} = require(\"../../helpers/chat/LLMPerformanceMonitor\");\nconst { v4: uuidv4 } = require(\"uuid\");\n\nclass KoboldCPPLLM {\n  constructor(embedder = null, modelPreference = null) {\n    const { OpenAI: OpenAIApi } = require(\"openai\");\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\n    this.className = \"KoboldCPPLLM\";\n    this.basePath = process.env.KOBOLD_CPP_BASE_PATH;\n    this.openai = new OpenAIApi({\n      baseURL: this.basePath,\n      apiKey: null,\n    });\n    this.model = modelPreference ?? process.env.KOBOLD_CPP_MODEL_PREF ?? null;\n    if (!this.model) throw new Error(\"KoboldCPP must have a valid model set.\");\n    this.limits = {\n      history: this.promptWindowLimit() * 0.15,\n      system: this.promptWindowLimit() * 0.15,\n      user: this.promptWindowLimit() * 0.7,\n    };\n\n    this.embedder = embedder ?? new NativeEmbedder();\n    this.defaultTemp = 0.7;\n    this.maxTokens = Number(process.env.KOBOLD_CPP_MAX_TOKENS) || 2048;\n    this.log(`Inference API: ${this.basePath} Model: ${this.model}`);\n  }\n\n  log(text, ...args) {\n    console.log(`\\x1b[36m[${this.className}]\\x1b[0m ${text}`, ...args);\n  }\n\n  #appendContext(contextTexts = []) {\n    if (!contextTexts || !contextTexts.length) return \"\";","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/Mintplex-Labs/anything-llm/blob/526360e320da9d1b36074be5ed64fe76e5bbfbbd/server/utils/AiProviders/koboldCPP/index.js#L9-L45","documentation":"Thrown by the KoboldCPP provider constructor when no model name can be resolved. The constructor tries the workspace-supplied modelPreference first, then falls back to the KOBOLD_CPP_MODEL_PREF environment variable, and finally defaults to null. If all three resolve to a falsy value, the constructor aborts, preventing the OpenAI-compatible client from being used without a model identifier.","triggerScenarios":"Instantiating `new KoboldCPPLLM(embedder, model)` (or selecting the 'koboldcpp' provider through getLLMProvider) where both the `model` argument is null/undefined/empty-string AND process.env.KOBOLD_CPP_MODEL_PREF is unset or empty. The `??` operator means empty-string from the param is overridden only if truly nullish (null/undefined), not if it is an empty string.","commonSituations":"User selects KoboldCPP as the LLM provider in workspace settings but never picks a model from the dropdown. The .env file has the KOBOLD_CPP_BASE_PATH set (so it passes the earlier base-path guard) but omits KOBOLD_CPP_MODEL_PREF. A workspace that was previously configured with a model that was later removed or renamed on the KoboldCPP server.","solutions":["Set KOBOLD_CPP_MODEL_PREF in your .env to a valid model loaded by your KoboldCPP server (e.g. KOBOLD_CPP_MODEL_PREF='koboldcpp/codellama-7b-instruct.Q4_K_S') and restart the server.","Select a specific model in the AnythingLLM workspace LLM settings UI so the modelPreference argument is populated.","Verify the model name matches what KoboldCPP reports via its /v1/models endpoint — a mismatch won't throw here but will fail later."],"exampleFix":"// before: .env has base path but no model\nKOBOLD_CPP_BASE_PATH='http://localhost:5001/v1'\n\n// after: add the model pref\nKOBOLD_CPP_BASE_PATH='http://localhost:5001/v1'\nKOBOLD_CPP_MODEL_PREF='koboldcpp/codellama-7b-instruct.Q4_K_S'","handlingStrategy":"validation","validationCode":"function validateKoboldCPPModel(modelPreference) {\n  const model = modelPreference ?? process.env.KOBOLD_CPP_MODEL_PREF ?? null;\n  if (!model) {\n    throw new Error(\n      'KOBOLD_CPP_MODEL_PREF is not set and no model was provided. ' +\n      'Set KOBOLD_CPP_MODEL_PREF in .env or pass a model name.'\n    );\n  }\n  return model;\n}\n\n// Call before instantiating the provider:\nconst model = validateKoboldCPPModel(workspaceModel);\nnew KoboldCPPLLM(embedder, model);","typeGuard":"/** @returns {model is string} */\nfunction isValidModelName(model) {\n  return typeof model === 'string' && model.trim().length > 0;\n}","tryCatchPattern":"let llm;\ntry {\n  llm = new KoboldCPPLLM(embedder, workspaceModel);\n} catch (e) {\n  if (e.message.includes('valid model set')) {\n    // Surface a user-friendly configuration error\n    return respondWithConfigError('Please select a KoboldCPP model in settings.');\n  }\n  throw e;\n}","preventionTips":["Always set KOBOLD_CPP_MODEL_PREF in .env even if you plan to use workspace-level model selection.","Use a startup health check that verifies all required env vars for the selected provider before accepting requests.","Validate model availability by querying KoboldCPP's /v1/models endpoint at startup."],"tags":["koboldcpp","configuration","env-var","constructor","model-selection"],"backgroundTag":null,"analyzedSha":"526360e320da9d1b36074be5ed64fe76e5bbfbbd","analyzedAt":"2026-08-13T01:45:47.170Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}