{"record":{"id":"29afd1142758bc16","repo":"mastra-ai/mastra","slug":"for-custom-model-modelname-is-required-in-sparset","errorCode":null,"errorMessage":"For custom model, modelName is required in SparseTextEmbedding.init","messagePattern":"For custom model, modelName is required in SparseTextEmbedding\\.init","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/fastembed/src/fastembed.ts","lineNumber":454,"sourceCode":"  }\n\n  static async init(options: InitSparseStandardOptions): Promise<SparseTextEmbedding>;\n  static async init(options: InitSparseCustomOptions): Promise<SparseTextEmbedding>;\n  static async init({\n    model = SparseEmbeddingModel.SpladePPEnV1,\n    executionProviders = [ExecutionProvider.CPU],\n    maxLength = 512,\n    cacheDir = 'local_cache',\n    showDownloadProgress = true,\n    modelAbsoluteDirPath = '',\n    modelName = '',\n  }: Partial<InitSparseOptions> = {}) {\n    if (model === SparseEmbeddingModel.CUSTOM) {\n      if (!modelAbsoluteDirPath) {\n        throw new Error('For custom model, modelAbsoluteDirPath is required in SparseTextEmbedding.init');\n      }\n      if (!modelName) {\n        throw new Error('For custom model, modelName is required in SparseTextEmbedding.init');\n      }\n    }\n\n    const modelDir =\n      model === SparseEmbeddingModel.CUSTOM\n        ? modelAbsoluteDirPath\n        : await SparseTextEmbedding.retrieveModel(model, cacheDir, showDownloadProgress);\n\n    const { tokenizer } = this.loadTokenizer(modelDir, maxLength);\n\n    const defaultModelName = 'model.onnx';\n    const modelPath = path.join(modelDir.toString(), 'onnx', modelName || defaultModelName);\n\n    if (!fs.existsSync(modelPath)) {\n      throw new Error(`Model file not found at ${modelPath}`);\n    }\n\n    const session = await ort.InferenceSession.create(modelPath, {","sourceCodeStart":436,"sourceCodeEnd":472,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/fastembed/src/fastembed.ts#L436-L472","documentation":"SparseTextEmbedding.init() throws this when model is SparseEmbeddingModel.CUSTOM but no modelName option was provided. The custom model loader needs the ONNX filename inside the model directory to build the inference session.","triggerScenarios":"Calling SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: '...' }) without modelName.","commonSituations":"Developer supplies the directory but assumes the ONNX filename is inferred; refactored code dropped the modelName field; typo'd option name means destructuring leaves it ''.","solutions":["Pass modelName with the ONNX file name inside <modelAbsoluteDirPath>/onnx/ (e.g. 'model.onnx').","If your file is named the default 'model.onnx', either pass it explicitly or check whether an empty-string override is masking the default.","Confirm the option key spelling is exactly modelName."],"exampleFix":"// before\nawait SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: dir });\n// after\nawait SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: dir, modelName: 'model.onnx' });","handlingStrategy":"validation","validationCode":"function assertSparseInitOptions(opts) {\n  if (opts.model === SparseEmbeddingModel.CUSTOM && !opts.modelName) {\n    throw new Error('modelName is required for SparseEmbeddingModel.CUSTOM');\n  }\n}","typeGuard":"function hasModelName(opts) {\n  return typeof opts.modelName === 'string' && opts.modelName.length > 0;\n}","tryCatchPattern":"try {\n  await SparseTextEmbedding.init(opts);\n} catch (e) {\n  if (e.message.includes('modelName is required')) {\n    console.error('Pass modelName (the ONNX filename) for CUSTOM models');\n  }\n  throw e;\n}","preventionTips":["Pair modelAbsoluteDirPath and modelName together in a single config object so one cannot exist without the other.","Always pass modelName explicitly, even when it is the default 'model.onnx'.","Type options as InitSparseOptions (not Partial) at call sites to get compile-time feedback."],"tags":["validation","configuration","fastembed"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}