mastra-ai/mastra · error · Error

For custom model, modelAbsoluteDirPath is required in Sparse

Error message

For custom model, modelAbsoluteDirPath is required in SparseTextEmbedding.init

What it means

SparseTextEmbedding.init() throws this when model is SparseEmbeddingModel.CUSTOM but no modelAbsoluteDirPath option was provided. Custom models are loaded from a local directory, so the library cannot proceed without it.

Source

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

    private session: ort.InferenceSession,
  ) {
    super();
  }

  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}`);

View on GitHub (pinned to 75dd419e61)

Solutions

Pass modelAbsoluteDirPath pointing to the directory containing the ONNX model and tokenizer files.
Verify the options object actually includes modelAbsoluteDirPath and that it is not an empty string.
If you meant a built-in model, use a non-CUSTOM SparseEmbeddingModel value instead.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
  await SparseTextEmbedding.init(opts);
} catch (e) {
  if (e.message.includes('modelAbsoluteDirPath is required')) {
    console.error('Provide modelAbsoluteDirPath when model is CUSTOM');
  }
  throw e;
}

Prevention

Use TypeScript with the full InitSparseOptions type and avoid Partial defaults silently emptying strings.
Centralize custom-model init in one factory function that validates options.
Document that CUSTOM differs from built-in models and always requires a local dir.

When it happens

Trigger: Calling SparseTextEmbedding.init({ model: SparseEmbeddingModel.CUSTOM }) with modelAbsoluteDirPath omitted, empty string, or undefined.

Common situations: Developer forgets that CUSTOM is a special case requiring local paths; options object built dynamically and the path key dropped; empty-string default ('') from destructuring counts as missing.

Related errors

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