mastra-ai/mastra · error · Error

Context array cannot be empty if provided

Error message

Context array cannot be empty if provided

What it means

If `options.context` is provided to createContextRelevanceScorerLLM it must contain at least one entry; an empty array is rejected because there is no content to score relevance against. The factory treats an explicitly empty context as a configuration mistake rather than a valid 'no context' case.

Source

Thrown at packages/evals/src/scorers/llm/context-relevance/index.ts:77

  if (options.contextExtractor && isScorerRunInputForAgent(input) && isScorerRunOutputForAgent(output)) {
    return options.contextExtractor(input, output);
  }

  return options.context ?? [];
};

export function createContextRelevanceScorerLLM({
  model,
  options,
}: {
  model: MastraModelConfig;
  options: ContextRelevanceOptions;
}) {
  if (!options.context && !options.contextExtractor) {
    throw new Error('Either context or contextExtractor is required for Context Relevance scoring');
  }
  if (options.context && options.context.length === 0) {
    throw new Error('Context array cannot be empty if provided');
  }

  return createScorer<ScorerRunInputForLLMJudge, ScorerRunOutputForLLMJudge>({
    id: 'context-relevance-scorer',
    name: 'Context Relevance (LLM)',
    description: 'Evaluates how relevant and useful the provided context was for generating the agent response',
    judge: {
      model,
      instructions: CONTEXT_RELEVANCE_INSTRUCTIONS,
    },
    type: 'agent',
  })
    .analyze({
      description: 'Analyze the relevance and utility of provided context',
      outputSchema: analyzeOutputSchema,
      createPrompt: ({ run }) => {
        const userQuery = getUserMessageFromRunInput(run.input) ?? '';
        const agentResponse = getAssistantMessageFromRunOutput(run.output) ?? '';

View on GitHub (pinned to 75dd419e61)

Solutions

1. Guard the retrieval step: only construct the scorer when retrievedChunks.length > 0
2. If context may be empty, omit the context field and supply a contextExtractor that resolves at run time
3. Surface an upstream warning when retrieval returns zero chunks so empty arrays are not silently propagated

Example fix

// before
const scorer = createContextRelevanceScorerLLM({ model, options: { context: retrieved ?? [] } });
// after
const options = retrieved && retrieved.length > 0 ? { context: retrieved } : { contextExtractor: ({ input }) => input.context ?? [] };
const scorer = createContextRelevanceScorerLLM({ model, options });

if (opts.context && (!Array.isArray(opts.context) || opts.context.length === 0)) {
  throw new Error('context, when provided, must be a non-empty array');
}

function isNonEmptyContext(o) {
  return !('context' in o) || (Array.isArray(o.context) && o.context.length > 0);
}

try {
  const scorer = createContextRelevanceScorerLLM({ model, options });
} catch (e) {
  if (e.message.includes('Context array cannot be empty')) {
    console.warn('Retrieval returned zero chunks; falling back to runtime extractor');
  }
  throw e;
}

When it happens

Trigger: Calling createContextRelevanceScorerLLM({ model, options: { context: [] } }) — a context key that exists but has zero elements, typically from an upstream retrieval step that returned no documents.

Common situations: A RAG retriever returned an empty result set and its output was passed straight through as context; a filter on retrieved chunks removed everything; initializing context as [] before an async fetch and constructing the scorer before the fetch resolves.

Related errors

• NO_SCORERS_PROVIDED
• Either context or contextExtractor is required for Context R
• createMultiTurnJudgeScorer: options.scale must be a finite n
• Both baselineResponse and noisyQuery are required for Noise
• Google RBAC roleMapping is required.

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