mastra-ai/mastra · error · Error

Model file not found at ${modelPath}

Error message

Model file not found at ${modelPath}

What it means

After resolving modelDir and the ONNX filename (explicit modelName or a default like model.onnx / model_optimized.onnx), init checks fs.existsSync on the joined path before creating the onnxruntime InferenceSession. If the file is missing it throws with the full resolved path. This catches bad paths, wrong filenames, and incomplete downloads before ORT fails with a less clear error.

Source

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

      }
      if (!modelName) {
        throw new Error('For custom model, modelName is required in FlagEmbedding.init');
      }
    }

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

    const tokenizer = loadTokenizerFromDir(modelDir, maxLength);
    const defaultModelName =
      model === EmbeddingModel.MLE5Large || model === EmbeddingModel.AllMiniLML6V2
        ? 'model.onnx'
        : 'model_optimized.onnx';
    const modelPath = path.join(modelDir.toString(), modelName || defaultModelName);
    if (!fs.existsSync(modelPath)) {
      throw new Error(`Model file not found at ${modelPath}`);
    }
    const session = await ort.InferenceSession.create(modelPath, {
      executionProviders,
      graphOptimizationLevel: 'all',
    });
    return new FlagEmbedding(tokenizer, session, model);
  }

  private static async downloadFileFromGCS(
    outputFilePath: PathLike,
    model: string,
    showDownloadProgress: boolean = true,
  ): Promise<PathLike> {
    if (fs.existsSync(outputFilePath)) {
      return outputFilePath;
    }

    // The AllMiniLML6V2 model URL doesn't follow the same naming convention as the other models

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Verify the exact file exists: ls <modelDir> and make modelName match (including extension).
  2. For CUSTOM, ensure the .onnx file was actually copied into modelAbsoluteDirPath alongside the tokenizer files.
  3. For built-in models, clear the corrupted cache directory and re-init with showDownloadProgress: true to re-download.
  4. In ephemeral CI, cache the model directory between jobs or download it in a setup step.

Example fix

// before
await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine', modelName: 'model.onx' });
// after
await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine', modelName: 'model.onnx' }); // matches file on disk
Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';
const modelPath = path.join(modelAbsoluteDirPath, modelName);
if (!fs.existsSync(modelPath)) {
  throw new Error(`ONNX weights missing at ${modelPath}; re-download or fix modelName`);
}

Try / catch

try {
  const embedder = await FlagEmbedding.init(opts);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Model file not found')) {
    // trigger model download / fix path, then retry once
  } else throw err;
}

Prevention

When it happens

Trigger: FlagEmbedding.init where <modelDir>/<modelName> does not exist — CUSTOM model with a modelName that doesn't match the actual file, a built-in model whose cached download is incomplete, or a platform-specific default name (model.onnx vs model_optimized.onnx) not present in a custom dir.

Common situations: Typoed modelName ('model.onx'); pointing modelAbsoluteDirPath at the parent of the model folder; cache wiped between runs by ephemeral CI filesystems; copying the ONNX file under a different name than passed.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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