{"record":{"id":"cb0507ed70204bfb","repo":"mastra-ai/mastra","slug":"hook-extractor-name-cannot-include-instructio","errorCode":null,"errorMessage":"Hook extractor \"${name}\" cannot include instructions or a schema.","messagePattern":"Hook extractor \"(.+?)\" cannot include instructions or a schema\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/extractor.ts","lineNumber":158,"sourceCode":"    const name = config.name.trim();\n    const instructions = typeof config.instructions === 'string' ? config.instructions.trim() : undefined;\n    const slug = slugifyExtractorName(name);\n    const isHook = config.mode === 'hook';\n\n    if (!name) {\n      throw new Error('Extractor name is required.');\n    }\n    if (!isHook && !config.instructions) {\n      throw new Error(`Extractor \"${name}\" must include instructions.`);\n    }\n    if (instructions !== undefined && !instructions) {\n      throw new Error(`Extractor \"${name}\" must include instructions.`);\n    }\n    if (isHook && !config.onExtracted) {\n      throw new Error(`Hook extractor \"${name}\" must include an onExtracted handler.`);\n    }\n    if (isHook && (config.instructions || config.schema)) {\n      throw new Error(`Hook extractor \"${name}\" cannot include instructions or a schema.`);\n    }\n    assertValidSlug(slug, name);\n    if (!internal && RESERVED_XML_TAGS.has(slug)) {\n      throw new Error(`Extractor slug \"${slug}\" is reserved by Observational Memory.`);\n    }\n\n    this.name = name;\n    this.slug = slug;\n    this.instructionsConfig = config.instructions ?? '';\n    this.schemaConfig = config.schema;\n    this.instructions = instructions ?? '';\n    this.schema = (\n      isHook ? z.unknown() : typeof config.schema === 'function' ? z.string() : (config.schema ?? z.string())\n    ) as z.ZodType<T>;\n    this.mode = isHook ? 'hook' : internal || !config.schema ? 'inline' : 'structured';\n    this.includePreviousExtraction = isHook ? false : (config.includePreviousExtraction ?? true);\n    this.metadataKeyPath = isHook ? false : (config.metadataKeyPath ?? `extracted.${slug}`);\n    this.onExtracted = config.onExtracted;","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/extractor.ts#L140-L176","documentation":"Hook extractors run after observation without contributing to the extraction prompt, so `instructions` and `schema` are meaningless (and misleading) for them. The library throws this in the constructor when `mode: 'hook'` is combined with either `config.instructions` or `config.schema` set.","triggerScenarios":"new Extractor({ name: 'X', mode: 'hook', instructions: '...' }); new Extractor({ name: 'X', mode: 'hook', schema: z.string() }); leaving `instructions`/`schema` in a shared config object when switching an extractor to hook mode.","commonSituations":"Converting an existing inline/structured extractor to hook mode by only toggling mode; spreading a base config containing instructions/schema into a hook extractor; TypeScript types allow it because fields are optional.","solutions":["Remove `instructions` and `schema` from the hook extractor config.","If you need prompt-driven or schema-validated extraction, drop `mode: 'hook'` and keep instructions/schema instead.","Move any transformation logic into `onExtracted`, which is the only work surface for hook extractors."],"exampleFix":"// before\nnew Extractor({ name: 'Audit', mode: 'hook', schema: z.string() });\n// after\nnew Extractor({\n  name: 'Audit',\n  mode: 'hook',\n  onExtracted: ({ current }) => current,\n});","handlingStrategy":"validation","validationCode":"if (config.mode === 'hook' && (config.instructions || config.schema)) {\n  throw new Error(`Hook extractor \"${config.name}\" must not define instructions/schema`);\n}","typeGuard":"function isCleanHookConfig(c) {\n  return c.mode !== 'hook' || (c.instructions === undefined && c.schema === undefined);\n}","tryCatchPattern":"try {\n  const extractor = new Extractor(config);\n} catch (e) {\n  if (e.message.includes('cannot include instructions or a schema')) {\n    logger.error('Hook extractor has prompt-only fields set', { name: config.name });\n  } else { throw e; }\n}","preventionTips":["When converting an extractor to hook mode, delete instructions and schema explicitly.","Keep hook and prompt extractor configs as separate factory functions so fields can't leak across.","Review spread-based config composition for leftover prompt fields."],"tags":["config","mutually-exclusive-options","observational-memory"],"backgroundTag":"incompatible-options-combination","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}