mastra-ai/mastra · error · Error

For custom model, modelName is required in SparseTextEmbeddi

Error message

For custom model, modelName is required in SparseTextEmbedding.init

What it means

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.

Source

Thrown at packages/fastembed/src/fastembed.ts:454

  }

  static async init(options: InitSparseStandardOptions): Promise<SparseTextEmbedding>;
  static async init(options: InitSparseCustomOptions): Promise<SparseTextEmbedding>;
  static async init({
    model = SparseEmbeddingModel.SpladePPEnV1,
    executionProviders = [ExecutionProvider.CPU],
    maxLength = 512,
    cacheDir = 'local_cache',
    showDownloadProgress = true,
    modelAbsoluteDirPath = '',
    modelName = '',
  }: Partial<InitSparseOptions> = {}) {
    if (model === SparseEmbeddingModel.CUSTOM) {
      if (!modelAbsoluteDirPath) {
        throw new Error('For custom model, modelAbsoluteDirPath is required in SparseTextEmbedding.init');
      }
      if (!modelName) {
        throw new Error('For custom model, modelName is required in SparseTextEmbedding.init');
      }
    }

    const modelDir =
      model === SparseEmbeddingModel.CUSTOM
        ? modelAbsoluteDirPath
        : await SparseTextEmbedding.retrieveModel(model, cacheDir, showDownloadProgress);

    const { tokenizer } = this.loadTokenizer(modelDir, maxLength);

    const defaultModelName = 'model.onnx';
    const modelPath = path.join(modelDir.toString(), 'onnx', modelName || defaultModelName);

    if (!fs.existsSync(modelPath)) {
      throw new Error(`Model file not found at ${modelPath}`);
    }

    const session = await ort.InferenceSession.create(modelPath, {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass modelName with the ONNX file name inside <modelAbsoluteDirPath>/onnx/ (e.g. 'model.onnx').
2. If your file is named the default 'model.onnx', either pass it explicitly or check whether an empty-string override is masking the default.
3. Confirm the option key spelling is exactly modelName.

Example fix

// before
await SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: dir });
// after
await SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: dir, modelName: 'model.onnx' });

function assertSparseInitOptions(opts) {
  if (opts.model === SparseEmbeddingModel.CUSTOM && !opts.modelName) {
    throw new Error('modelName is required for SparseEmbeddingModel.CUSTOM');
  }
}

function hasModelName(opts) {
  return typeof opts.modelName === 'string' && opts.modelName.length > 0;
}

try {
  await SparseTextEmbedding.init(opts);
} catch (e) {
  if (e.message.includes('modelName is required')) {
    console.error('Pass modelName (the ONNX filename) for CUSTOM models');
  }
  throw e;
}

When it happens

Trigger: Calling SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM, modelAbsoluteDirPath: '...' }) without modelName.

Common situations: 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 ''.

Related errors

• For custom model, modelAbsoluteDirPath is required in Sparse
• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/29afd1142758bc16. Report an issue: GitHub.