mastra-ai/mastra · error · Error

For custom model, modelAbsoluteDirPath is required in…

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.

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…
• A custom capture schema requires an onExtracted hook that…
• Agent response is required for prompt alignment scoring
• AGENT_SEND_STREAM_RESUME_MISSING_TARGET
• Both baselineResponse and noisyQuery are required for Noise…

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

Appendix: 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)