{"record":{"id":"dc0c69e268d89dd7","repo":"mastra-ai/mastra","slug":"custom-subconscious-reflection-agent-name-req","errorCode":null,"errorMessage":"Custom Subconscious reflection agent \"${name}\" requires instructions or agent.","messagePattern":"Custom Subconscious reflection agent \"(.+?)\" requires instructions or agent\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/index.ts","lineNumber":233,"sourceCode":"        `Subconscious observation extractor \"${name}\" shares the Observer model and does not accept model or maxSteps.`,\n      );\n    }\n    if (!('schema' in entry) || !entry.schema || !('onExtracted' in entry) || typeof entry.onExtracted !== 'function') {\n      throw new Error(`Custom Subconscious observation agent \"${name}\" requires schema and onExtracted.`);\n    }\n  }\n\n  #validateReflectionEntry(entry: SubconsciousReflectionEntry): void {\n    const name = entryName(entry);\n    if (typeof entry === 'string') {\n      if (!BUILT_IN_REFLECTION.has(name)) throw new Error(`Unknown Subconscious reflection agent: ${name}`);\n      return;\n    }\n    if (BUILT_IN_REFLECTION.has(name) && 'agent' in entry && entry.agent) {\n      throw new Error(`Built-in Subconscious reflection agent \"${name}\" cannot be replaced with a custom agent.`);\n    }\n    if (!BUILT_IN_REFLECTION.has(name) && !entry.instructions?.trim() && !('agent' in entry && entry.agent)) {\n      throw new Error(`Custom Subconscious reflection agent \"${name}\" requires instructions or agent.`);\n    }\n  }\n}\n\nexport {\n  buildSubconsciousActivitySnapshot,\n  publishSubconsciousActivity,\n  publishSubconsciousError,\n  renderSubconsciousActivity,\n  SUBCONSCIOUS_ACTIVITY_STATE_ID,\n} from './activity';\nexport type { SubconsciousActivitySnapshot, SubconsciousActivityUpdate } from './activity';\nexport { SubconsciousCaptureExtractor, subconsciousCaptureSchema } from './capture';\nexport { SubconsciousRemindExtractor } from './remind';\nexport {\n  createPinnedTools,\n  listPinnedKnowledge,\n  DEFAULT_MAX_PINS,","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/index.ts#L215-L251","documentation":"A custom (non-built-in) reflection entry must define its behavior either via instructions (non-empty string) or a custom agent object. If neither is present (instructions missing/blank and no agent), the constructor throws because the reflection would have nothing to run.","triggerScenarios":"new Subconscious({ reflection: [{ name: 'my-reflection' }] }), or instructions: '   ' (whitespace-only, caught by .trim()) with no agent key.","commonSituations":"Placeholder config left unfilled; instructions set to empty string from an unset env var; spread-merging config that drops instructions; forgetting that custom names require explicit behavior.","solutions":["Add non-empty instructions: { name: 'my-reflection', instructions: 'Summarize the user goals...' }.","Or attach a custom agent: { name: 'my-reflection', agent: myAgent }.","If it was meant to be built-in, use the built-in string name from BUILT_IN_REFLECTION."],"exampleFix":"// before\nnew Subconscious({ reflection: [{ name: 'weekly-review' }] });\n// after\nnew Subconscious({ reflection: [{ name: 'weekly-review', instructions: 'Review the week observations and summarize progress.' }] });","handlingStrategy":"validation","validationCode":"const entry = { name: 'weekly-review', instructions: process.env.REVIEW_INSTRUCTIONS ?? '' };\nif (!BUILT_IN_REFLECTION.has(entry.name) && !entry.instructions.trim() && !('agent' in entry)) {\n  throw new Error(`Reflection '${entry.name}' needs instructions or agent`);\n}","typeGuard":"function isUsableReflectionEntry(e: { name: string; instructions?: string; agent?: unknown }): boolean {\n  return BUILT_IN_REFLECTION.has(e.name) || !!e.instructions?.trim() || !!e.agent;\n}","tryCatchPattern":"try {\n  sub = new Subconscious({ reflection: [entry] });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('requires instructions or agent')) {\n    console.error(`Reflection '${entry.name}' has no behavior defined`);\n  } else throw e;\n}","preventionTips":["Validate env-sourced instructions are non-empty at startup (trim, not just truthy).","Default-fill instructions in config factories.","Add a constructor smoke test for your reflection config."],"tags":["configuration","validation","observational-memory"],"backgroundTag":"missing-required-field","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}