mastra-ai/mastra · error · MastraError

INVALID_AGENT_SCORERS

INVALID_AGENT_SCORERS

Error message

Agent scorers must be an array of scorers or an AgentScorerConfig

What it means

For agent targets, `scorers` must be either a plain array of scorers or an AgentScorerConfig object (with `agent`/`trajectory` keys). Any other value — a string, a single scorer object not in an array, a malformed config, or a workflow-shaped config on a non-workflow target — is rejected as a type/shape error before the run starts.

Source

Thrown at packages/core/src/evals/run/index.ts:807

        id: 'NO_SCORERS_PROVIDED',
        category: 'USER',
        text: 'At least one workflow, step, or trajectory scorer must be provided',
      });
    }
  } else if (!isWorkflow(target) && isAgentScorerConfig(scorers)) {
    const hasScorers =
      (scorers.agent && scorers.agent.length > 0) || (scorers.trajectory && scorers.trajectory.length > 0);

    if (!hasScorers) {
      throw new MastraError({
        domain: 'SCORER',
        id: 'NO_SCORERS_PROVIDED',
        category: 'USER',
        text: 'At least one agent or trajectory scorer must be provided',
      });
    }
  } else if (!isWorkflow(target) && !Array.isArray(scorers) && !isAgentScorerConfig(scorers)) {
    throw new MastraError({
      domain: 'SCORER',
      id: 'INVALID_AGENT_SCORERS',
      category: 'USER',
      text: 'Agent scorers must be an array of scorers or an AgentScorerConfig',
    });
  }
}

async function executeTarget(
  target: Agent | Workflow,
  item: RunEvalsDataItem<any>,
  targetOptions?: RunEvalsAgentOptions | WorkflowRunOptions,
) {
  try {
    if (isWorkflow(target)) {
      return await executeWorkflow(target, item, targetOptions as WorkflowRunOptions);
    } else if (item.turns && Array.isArray(item.turns) && item.turns.length > 0) {
      return await executeAgentTurns(target, item, targetOptions as RunEvalsAgentOptions);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Wrap a single scorer in an array: `scorers: [myScorer]`
2. For keyed configs on agent targets, use the AgentScorerConfig shape: `{ agent: [...], trajectory: [...] }`
3. If you intended workflow/step scorers, set `target` to the Workflow — the object shape must match the target kind

Example fix

// before
runEvals({ target: agent, scorers: myScorer, data });
// after
runEvals({ target: agent, scorers: [myScorer], data });

function assertScorersShape(scorers, isWf) {
  const ok = Array.isArray(scorers) || (typeof scorers === 'object' && scorers !== null && (isWf ? true : ('agent' in scorers || 'trajectory' in scorers)));
  if (!ok) throw new Error('scorers must be an array of scorers or a valid config object');
}

function isScorerArray(s: unknown): s is unknown[] {
  return Array.isArray(s);
}
function isAgentScorerConfigLike(s: unknown): s is { agent?: unknown[]; trajectory?: unknown[] } {
  return typeof s === 'object' && s !== null && ('agent' in s || 'trajectory' in s);
}

try {
  await runEvals({ target, scorers, data });
} catch (e) {
  if (e instanceof MastraError && e.id === 'INVALID_AGENT_SCORERS') {
    throw new TypeError(`Bad scorers argument: ${e.message}. Wrap single scorers in an array.`);
  }
  throw e;
}

When it happens

Trigger: Passing a single scorer object directly instead of wrapping it in an array (`scorers: myScorer`); passing a string scorer ID; passing `{ steps: ... }` or `{ workflow: ... }` config while the target is an agent; scorers loaded from JSON losing their expected shape.

Common situations: Migrating from older APIs that accepted a bare scorer; copy-pasting workflow scorer configs into agent runs; YAML/JSON config parsing producing strings or unexpected structures.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Plugin entry must be a .ts file
• Invalid model provided. Model must be a MastraLanguageModel
• NO_SCORERS_PROVIDED
• Invalid model configuration provided
• Either context or contextExtractor is required for Context R

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