mastra-ai/mastra · error · Error

Extractor name is required.

Error message

Extractor name is required.

What it means

The Extractor constructor trims config.name and requires a non-empty name; extractors are identified by their name/slug throughout observational memory. An empty or whitespace-only name throws immediately.

Source

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

  readonly schema: z.ZodType<T>;
  readonly mode: ExtractorMode;
  readonly includePreviousExtraction: boolean;
  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.`);
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide a non-empty, descriptive name when constructing the Extractor
2. Validate config before construction (skip or fail entries without names)
3. In form/UI flows, require the name field before creating the extractor

Example fix

// before
new Extractor({ name: config.name ?? '', instructions: '...' });

// after
if (!config.name?.trim()) throw new Error('Extractor config must include a name');
new Extractor({ name: config.name.trim(), instructions: '...' });

const assertNamed = (cfg: ExtractorConfig) => {
  if (typeof cfg.name !== 'string' || !cfg.name.trim()) {
    throw new Error('Extractor config.name is required and must be non-empty');
  }
};
assertNamed(config);

const hasName = (cfg: Partial<ExtractorConfig>): cfg is ExtractorConfig =>
  typeof cfg.name === 'string' && cfg.name.trim().length > 0;

try {
  const extractor = new Extractor(config);
} catch (err) {
  if (err instanceof Error && err.message === 'Extractor name is required.') {
    console.error('Extractor definition missing name:', config);
  }
  throw err;
}

When it happens

Trigger: new Extractor({ name: '' or ' ' , ...}); building extractors from external config where name is optional/blank; destructuring a record that lacks a name field.

Common situations: Loading extractor definitions from JSON/YAML where a name key was omitted; user-submitted extractor forms submitted with a blank name; mapping over arrays where some items are placeholders.

Related errors

• Extractor name "${name}" must produce a non-empty slug.
• Extractor name "${name}" produced invalid slug "${slug}".
• Extractor metadataKeyPath "${keyPath}" contains an unsafe pa
• Extractor slug "${slug}" is reserved by Observational Memory
• Extractor slug "${extractor.slug}" is reserved by Observatio

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