mastra-ai/mastra · error · MastraError

MASTR_SCORER_FAILED_TO_RUN_MISSING_MODEL_OR_INSTRUCTIONS

MASTR_SCORER_FAILED_TO_RUN_MISSING_MODEL_OR_INSTRUCTIONS

Error message

Step "${scorerStep.name}" requires a model and instructions

What it means

A judge step needs both a model (to call the LLM) and instructions (the prompt rubric). When `modelConfig` or `instructions` resolve to undefined after falling back from `originalStep.judge` to `this.config.judge`, a MastraError (id MASTR_SCORER_FAILED_TO_RUN_MISSING_MODEL_OR_INSTRUCTIONS, category USER) is thrown. This is a user configuration error: the scorer was defined without a complete judge configuration.

Source

Thrown at packages/core/src/evals/base.ts:1401

    const onFinish = originalStep.judge?.onFinish ?? this.config.judge?.onFinish;
    const maxSteps = originalStep.judge?.maxSteps ?? this.config.judge?.maxSteps;
    const inputProcessors = originalStep.judge?.inputProcessors ?? this.config.judge?.inputProcessors;
    const outputProcessors = originalStep.judge?.outputProcessors ?? this.config.judge?.outputProcessors;
    const errorProcessors = originalStep.judge?.errorProcessors ?? this.config.judge?.errorProcessors;
    const maxProcessorRetries = originalStep.judge?.maxProcessorRetries ?? this.config.judge?.maxProcessorRetries;
    const memoryOptions = stepMemoryOptions
      ? {
          ...defaultMemoryOptions,
          ...stepMemoryOptions,
          options:
            defaultMemoryOptions?.options || stepMemoryOptions.options
              ? { ...defaultMemoryOptions?.options, ...stepMemoryOptions.options }
              : undefined,
        }
      : defaultMemoryOptions;

    if (!modelConfig || !instructions) {
      throw new MastraError({
        id: 'MASTR_SCORER_FAILED_TO_RUN_MISSING_MODEL_OR_INSTRUCTIONS',
        domain: ErrorDomain.SCORER,
        category: ErrorCategory.USER,
        text: `Step "${scorerStep.name}" requires a model and instructions`,
        details: {
          scorerId: this.config.id ?? this.config.name,
          step: scorerStep.name,
        },
      });
    }

    // Resolve the model configuration to a LanguageModel instance
    // Pass the Mastra instance to enable custom gateway resolution
    const resolvedModel = await resolveModelConfig(
      modelConfig,
      this.config.judge?.requestContext ?? undefined,
      this.#mastra,
    );

View on GitHub (pinned to 75dd419e61)

Solutions

Add both `judge.model` and `judge.instructions` to the scorer config
Or set them per-step in the step's `judge` block so the fallback resolves for every step
Use a model helper (e.g. `openai('gpt-4o')`) to guarantee a valid model instance instead of a possibly-undefined string/env value
Log/print the resolved `modelConfig` and `instructions` before running to confirm they are non-null

Example fix

// before
const scorer = new MastraScorer({ id: 'tone' }); // no judge
// after
const scorer = new MastraScorer({
  id: 'tone',
  judge: {
    model: openai('gpt-4o'),
    instructions: 'Rate the response tone from 1-5 and explain.',
  },
});

Defensive patterns

Strategy: validation

Validate before calling

function validateJudgeConfig(config) {
  const judge = config.judge ?? {};
  if (!judge.model || !judge.instructions) {
    throw new Error(`Scorer "${config.id ?? config.name}" needs judge.model and judge.instructions`);
  }
}
validateJudgeConfig(scorerConfig); // before constructing/running

Type guard

function hasCompleteJudge(c: { judge?: { model?: unknown; instructions?: unknown } }):
  c is { judge: { model: NonNullable<typeof c.judge>['model']; instructions: string } } {
  return !!c.judge && !!c.judge.model && typeof c.judge.instructions === 'string' && c.judge.instructions.length > 0;
}

Try / catch

try {
  await scorer.run(runInput);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTR_SCORER_FAILED_TO_RUN_MISSING_MODEL_OR_INSTRUCTIONS') {
    console.error(`Scorer ${e.details.scorerId}: set judge.model and judge.instructions`);
  } else throw e;
}

Prevention

Always define the judge block at scorer level as the default for all steps
Centralize judge model/instructions in a factory helper so they can't be omitted
Assert judge config completeness in unit tests for every scorer

When it happens

Trigger: Running a scorer whose step has no `judge.model` and the scorer-level `config.judge.model` is also missing (or the same for `instructions`) — e.g. `new MastraScorer({ id })` with no judge block, or a step-level judge overriding only one of the two fields while the top-level judge is absent.

Common situations: Creating a scorer with only `name`/`id` and forgetting the `judge` config; setting `judge.instructions` but no `judge.model` (or vice versa); env-based model resolution (e.g. missing OPENAI_API_KEY helper) returning undefined at construction time; copy-pasting a scorer template and deleting the judge block.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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