mastra-ai/mastra · error · Error

Extractor "${this.name}" must include instructions.

Error message

Extractor "${this.name}" must include instructions.

What it means

`Extractor.resolve()` re-evaluates dynamic (function-valued) `instructions` at runtime for each extraction pass, using the ProcessorContext. This mirrors the constructor guard: if the resolved instructions — including the result of calling the configured function — trim to an empty string, extraction cannot proceed and the error is thrown. This catches dynamic instruction providers that return blank content for a given context.

Source

Thrown at packages/memory/src/processors/observational-memory/extractor.ts:191

    this.mode = isHook ? 'hook' : internal || !config.schema ? 'inline' : 'structured';
    this.includePreviousExtraction = isHook ? false : (config.includePreviousExtraction ?? true);
    this.metadataKeyPath = isHook ? false : (config.metadataKeyPath ?? `extracted.${slug}`);
    this.onExtracted = config.onExtracted;
    this.retryStructuredExtractionOnEmptyObject = config.retryStructuredExtractionOnEmptyObject ?? false;
    this.internal = internal;
  }

  async resolve(context: ExtractorRuntimeContext): Promise<Extractor<T>> {
    if (this.mode === 'hook') {
      return this;
    }

    const instructions =
      typeof this.instructionsConfig === 'function'
        ? (await this.instructionsConfig(context)).trim()
        : this.instructionsConfig.trim();
    if (!instructions) {
      throw new Error(`Extractor "${this.name}" must include instructions.`);
    }

    const schema = typeof this.schemaConfig === 'function' ? await this.schemaConfig(context) : this.schemaConfig;
    return new Extractor(
      {
        name: this.name,
        instructions,
        ...(schema ? { schema } : {}),
        includePreviousExtraction: this.includePreviousExtraction,
        metadataKeyPath: this.metadataKeyPath,
        onExtracted: this.onExtracted,
        retryStructuredExtractionOnEmptyObject: this.retryStructuredExtractionOnEmptyObject,
      },
      this.internal,
    );
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Make the instruction function return a non-empty fallback string when dynamic data is missing.
  2. Validate inside the function that its inputs are present before returning.
  3. If instructions are genuinely static, pass a plain string instead of a function to surface the error earlier (at construction).

Example fix

// before
instructions: async ({ requestContext }) => `Focus on ${requestContext.get('topic')}`;
// after
instructions: async ({ requestContext }) => {
  const topic = requestContext?.get('topic');
  return topic ? `Focus on ${topic}` : 'Extract key user facts.';
}
Defensive patterns

Strategy: validation

Validate before calling

const resolved = typeof instructions === 'function' ? await instructions(context) : instructions;
if (!resolved?.trim()) throw new Error('Dynamic instructions resolved to blank');

Type guard

function resolvesToInstructions(fn) { return typeof fn === 'function'; } // then validate its return value non-blank at runtime

Try / catch

try {
  await extractor.resolve(context);
} catch (e) {
  if (e.message.includes('must include instructions')) {
    logger.warn('Dynamic instructions empty for context, using fallback', { name: extractor.name });
  } else { throw e; }
}

Prevention

When it happens

Trigger: instructions provided as a function that returns '' or whitespace for the current context (e.g. empty RequestContext, missing requestContext value used in a template); a non-hook extractor whose static instructionsConfig is '' — possible when the Extractor was built internally or via resolve() re-construction paths.

Common situations: Instructions built from requestContext/memory values that are absent at runtime; async function returning an empty template; environment-dependent prompt data not available in a worker/edge deployment.

Related errors

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