mastra-ai/mastra · error · Error

Extractor "${name}" must include instructions.

Error message

Extractor "${name}" must include instructions.

What it means

In Observational Memory, non-hook extractors contribute an instructions block to the observer/reflector prompt, so `instructions` is mandatory when constructing an `Extractor`. The library throws this error in the constructor when `mode` is not 'hook' and `config.instructions` is falsy (missing, undefined, null, or empty string). It enforces that every prompt-driven extractor describes what it should extract.

Source

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

  readonly metadataKeyPath: string | false;
  readonly onExtracted?: ExtractorConfig<T>['onExtracted'];
  readonly retryStructuredExtractionOnEmptyObject: boolean;
  /** @internal */
  readonly internal: boolean;
  private readonly instructionsConfig: ExtractorConfigValue<string>;
  private readonly schemaConfig?: ExtractorConfigValue<z.ZodType<T> | undefined>;

  constructor(config: ExtractorConfig<T>, internal = false) {
    const name = config.name.trim();
    const instructions = typeof config.instructions === 'string' ? config.instructions.trim() : undefined;
    const slug = slugifyExtractorName(name);
    const isHook = config.mode === 'hook';

    if (!name) {
      throw new Error('Extractor name is required.');
    }
    if (!isHook && !config.instructions) {
      throw new Error(`Extractor "${name}" must include instructions.`);
    }
    if (instructions !== undefined && !instructions) {
      throw new Error(`Extractor "${name}" must include instructions.`);
    }
    if (isHook && !config.onExtracted) {
      throw new Error(`Hook extractor "${name}" must include an onExtracted handler.`);
    }
    if (isHook && (config.instructions || config.schema)) {
      throw new Error(`Hook extractor "${name}" cannot include instructions or a schema.`);
    }
    assertValidSlug(slug, name);
    if (!internal && RESERVED_XML_TAGS.has(slug)) {
      throw new Error(`Extractor slug "${slug}" is reserved by Observational Memory.`);
    }

    this.name = name;
    this.slug = slug;
    this.instructionsConfig = config.instructions ?? '';

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a non-empty `instructions` string describing what the extractor should return.
2. If the extractor should run purely as a post-processing callback, set `mode: 'hook'` and provide `onExtracted` instead.
3. Check that the variable holding instructions is defined and not trimmed down to an empty string before construction.

Example fix

// before
const e = new Extractor({ name: 'User Preferences' });
// after
const e = new Extractor({
  name: 'User Preferences',
  instructions: 'Extract durable user preferences from observations.',
});

function assertExtractorConfig(config) {
  if (config.mode !== 'hook' && !config.instructions) {
    throw new Error(`Extractor "${config.name}" must include instructions.`);
  }
}

function hasInstructions(c) { return typeof c.instructions === 'string' && c.instructions.trim().length > 0; }

try {
  const extractor = new Extractor(config);
} catch (e) {
  if (e.message.includes('must include instructions')) {
    logger.error('Extractor misconfigured: missing instructions', { name: config.name });
  } else { throw e; }
}

When it happens

Trigger: new Extractor({ name: 'X' }) without instructions; new Extractor({ name: 'X', mode: 'inline' }) with instructions omitted; instructions passed as empty string ''; a dynamic instruction function accidentally not passed (e.g. undefined variable).

Common situations: Hand-writing an extractor config and forgetting the prompt text; copying a hook-mode example but leaving mode: 'hook' off; refactoring so instructions became an undefined variable; testing with a stub config.

Related errors

• ModelByInputTokens threshold keys must be positive numbers.
• ModelByInputTokens requires a valid model target for thresho
• Cookie password must be at least 32 characters. Set WORKOS_C
• Factory rule version is required.
• ${label} must be an object.

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