mastra-ai/mastra · error · Error

For custom model, modelName is required in FlagEmbedding.ini

Error message

For custom model, modelName is required in FlagEmbedding.init

What it means

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.

Source

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

  }

  static async init(options: InitStandardOptions): Promise<FlagEmbedding>;
  static async init(options: InitCustomOptions): Promise<FlagEmbedding>;
  static async init({
    model = EmbeddingModel.BGESmallENV15,
    executionProviders = [ExecutionProvider.CPU],
    maxLength = 512,
    cacheDir = 'local_cache',
    showDownloadProgress = true,
    modelAbsoluteDirPath = '',
    modelName = '',
  }: Partial<InitOptions> = {}) {
    if (model === EmbeddingModel.CUSTOM) {
      if (!modelAbsoluteDirPath) {
        throw new Error('For custom model, modelAbsoluteDirPath is required in FlagEmbedding.init');
      }
      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, {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add modelName with the exact ONNX filename present in the directory, e.g. modelName: 'model.onnx'.
2. If the file is named model.onnx or model_optimized.onnx you still must pass it explicitly for CUSTOM.
3. ls the model dir to confirm the actual filename and match it exactly (case-sensitive).

Example fix

// before
await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine' });
// after
await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine', modelName: 'model.onnx' });

import fs from 'node:fs';
if (model === EmbeddingModel.CUSTOM) {
  if (!modelName) throw new Error('modelName (ONNX filename) is required for CUSTOM models');
  if (!fs.existsSync(path.join(modelAbsoluteDirPath, modelName))) {
    throw new Error(`${modelName} not found in ${modelAbsoluteDirPath}`);
  }
}

const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.length > 0;

try {
  const embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: dir, modelName });
} catch (err) {
  if (err instanceof Error && err.message.includes('modelName is required')) {
    // prompt operator / fall back to autodetected *.onnx filename
  } else throw err;
}

When it happens

Trigger: FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/mine' }) with no modelName option, an empty string, or a falsy variable (e.g. undefined env lookup).

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

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• For custom model, modelAbsoluteDirPath is required in FlagEm
• 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/164f29e553c8fea5. Report an issue: GitHub.