{"record":{"id":"164f29e553c8fea5","repo":"mastra-ai/mastra","slug":"for-custom-model-modelname-is-required-in-flagemb","errorCode":null,"errorMessage":"For custom model, modelName is required in FlagEmbedding.init","messagePattern":"For custom model, modelName is required in FlagEmbedding\\.init","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/fastembed/src/fastembed.ts","lineNumber":223,"sourceCode":"  }\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)) {\n      throw new Error(`Model file not found at ${modelPath}`);\n    }\n    const session = await ort.InferenceSession.create(modelPath, {","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/fastembed/src/fastembed.ts#L205-L241","documentation":"Alongside the directory path, CUSTOM models require modelName — the filename of the ONNX weights inside modelAbsoluteDirPath (e.g. 'model.onnx' or 'model_optimized.onnx'). Built-in models can infer a default filename, but CUSTOM cannot, so init throws if modelName is empty. The directory check (2137) runs first, so this fires only when the path was given but the name was not.","triggerScenarios":"FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine' }) with no modelName option, an empty string, or a falsy variable (e.g. undefined env lookup).","commonSituations":"Assuming the library auto-detects the ONNX file for custom dirs; the model file uses a non-standard name (e.g. custom_export.onnx) and no explicit name is supplied; modelName read from config that is missing for the custom entry.","solutions":["Add modelName with the exact ONNX filename present in the directory, e.g. modelName: 'model.onnx'.","If the file is named model.onnx or model_optimized.onnx you still must pass it explicitly for CUSTOM.","ls the model dir to confirm the actual filename and match it exactly (case-sensitive)."],"exampleFix":"// before\nawait FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine' });\n// after\nawait FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine', modelName: 'model.onnx' });","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nif (model === EmbeddingModel.CUSTOM) {\n  if (!modelName) throw new Error('modelName (ONNX filename) is required for CUSTOM models');\n  if (!fs.existsSync(path.join(modelAbsoluteDirPath, modelName))) {\n    throw new Error(`${modelName} not found in ${modelAbsoluteDirPath}`);\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, modelAbsoluteDirPath: dir, modelName });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('modelName is required')) {\n    // prompt operator / fall back to autodetected *.onnx filename\n  } else throw err;\n}","preventionTips":["Always pass both modelAbsoluteDirPath and modelName together for CUSTOM.","Derive modelName from a directory listing of *.onnx files at startup.","Keep custom model option values in one typed config object so they cannot diverge."],"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"}