mastra-ai/mastra · error · Error

For custom model, modelAbsoluteDirPath is required in FlagEm

Error message

For custom model, modelAbsoluteDirPath is required in FlagEmbedding.init

What it means

When model is EmbeddingModel.CUSTOM, FlagEmbedding.init cannot look up a known download source, so it requires modelAbsoluteDirPath pointing at a local directory containing the ONNX model and tokenizer files. If it is empty (the default ''), init throws immediately. This enforces that custom models are fully user-supplied.

Source

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

    private model: EmbeddingModel,
  ) {
    super();
  }

  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)) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass modelAbsoluteDirPath with an absolute path to the directory containing the ONNX model and tokenizer files.
2. Also pass modelName (the ONNX filename) — it is required for CUSTOM too.
3. Resolve env-var-driven paths before init and fail fast if empty.

Example fix

// before
const embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelName: 'model.onnx' });
// after
const embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, modelAbsoluteDirPath: '/models/bge-custom', modelName: 'model.onnx' });

import fs from 'node:fs';
const dir = process.env.CUSTOM_MODEL_DIR;
if (model === EmbeddingModel.CUSTOM) {
  if (!dir || !fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {
    throw new Error('Set CUSTOM_MODEL_DIR to an existing model directory');
  }
}

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

try {
  const embedder = await FlagEmbedding.init({ model: EmbeddingModel.CUSTOM, ...customOpts });
} catch (err) {
  if (err instanceof Error && err.message.includes('modelAbsoluteDirPath is required')) {
    // surface a clear config error to the operator
  } else throw err;
}

When it happens

Trigger: Calling FlagEmbedding.init({ model: EmbeddingModel.CUSTOM }) without modelAbsoluteDirPath, with an empty string, or with a falsy computed path (e.g. an env var that is unset defaulting to '').

Common situations: Switching from a built-in model to CUSTOM but forgetting to add the path; reading the path from process.env.CUSTOM_MODEL_DIR that is not set; typos in the options key (modelDirPath vs modelAbsoluteDirPath) leaving the real option unused.

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, modelName is required in FlagEmbedding.ini
• 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/9f8373369f0bb4d1. Report an issue: GitHub.