{"record":{"id":"9f8373369f0bb4d1","repo":"mastra-ai/mastra","slug":"for-custom-model-modelabsolutedirpath-is-required","errorCode":null,"errorMessage":"For custom model, modelAbsoluteDirPath is required in FlagEmbedding.init","messagePattern":"For custom model, modelAbsoluteDirPath is required in FlagEmbedding\\.init","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/fastembed/src/fastembed.ts","lineNumber":220,"sourceCode":"    private model: EmbeddingModel,\n  ) {\n    super();\n  }\n\n  static async init(options: InitStandardOptions): Promise<FlagEmbedding>;\n  static async init(options: InitCustomOptions): Promise<FlagEmbedding>;\n  static async init({\n    model = EmbeddingModel.BGESmallENV15,\n    executionProviders = [ExecutionProvider.CPU],\n    maxLength = 512,\n    cacheDir = 'local_cache',\n    showDownloadProgress = true,\n    modelAbsoluteDirPath = '',\n    modelName = '',\n  }: Partial<InitOptions> = {}) {\n    if (model === EmbeddingModel.CUSTOM) {\n      if (!modelAbsoluteDirPath) {\n        throw new Error('For custom model, modelAbsoluteDirPath is required in FlagEmbedding.init');\n      }\n      if (!modelName) {\n        throw new Error('For custom model, modelName is required in FlagEmbedding.init');\n      }\n    }\n\n    const modelDir =\n      model === EmbeddingModel.CUSTOM\n        ? modelAbsoluteDirPath\n        : await FlagEmbedding.retrieveModel(model, cacheDir, showDownloadProgress);\n\n    const tokenizer = loadTokenizerFromDir(modelDir, maxLength);\n    const defaultModelName =\n      model === EmbeddingModel.MLE5Large || model === EmbeddingModel.AllMiniLML6V2\n        ? 'model.onnx'\n        : 'model_optimized.onnx';\n    const modelPath = path.join(modelDir.toString(), modelName || defaultModelName);\n    if (!fs.existsSync(modelPath)) {","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/fastembed/src/fastembed.ts#L202-L238","documentation":"When model is EmbeddingModel.CUSTOM, FlagEmbedding.init cannot look up a known download source, so it requires modelAbsoluteDirPath pointing at a local directory containing the ONNX model and tokenizer files. If it is empty (the default ''), init throws immediately. This enforces that custom models are fully user-supplied.","triggerScenarios":"Calling FlagEmbedding.init({ model: EmbeddingModel.CUSTOM }) without modelAbsoluteDirPath, with an empty string, or with a falsy computed path (e.g. an env var that is unset defaulting to '').","commonSituations":"Switching from a built-in model to CUSTOM but forgetting to add the path; reading the path from process.env.CUSTOM_MODEL_DIR that is not set; typos in the options key (modelDirPath vs modelAbsoluteDirPath) leaving the real option unused.","solutions":["Pass modelAbsoluteDirPath with an absolute path to the directory containing the ONNX model and tokenizer files.","Also pass modelName (the ONNX filename) — it is required for CUSTOM too.","Resolve env-var-driven paths before init and fail fast if empty."],"exampleFix":"// before\nconst embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelName: 'model.onnx' });\n// after\nconst embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/bge-custom', modelName: 'model.onnx' });","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nconst dir = process.env.CUSTOM_MODEL_DIR;\nif (model === EmbeddingModel.CUSTOM) {\n  if (!dir || !fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {\n    throw new Error('Set CUSTOM_MODEL_DIR to an existing model directory');\n  }\n}","typeGuard":"const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.length > 0;","tryCatchPattern":"try {\n  const embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, ...customOpts });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('modelAbsoluteDirPath is required')) {\n    // surface a clear config error to the operator\n  } else throw err;\n}","preventionTips":["Validate CUSTOM options (dir + modelName) in a config layer before init.","Fail fast at startup if required env vars for custom models are unset.","Prefer built-in models unless you truly have a local checkpoint."],"tags":["validation","missing-argument","configuration","embeddings"],"backgroundTag":"missing-required-argument","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}