{"record":{"id":"b21a19f1a3e09930","repo":"mastra-ai/mastra","slug":"built-in-subconscious-reflection-agent-name-c","errorCode":null,"errorMessage":"Built-in Subconscious reflection agent \"${name}\" cannot be replaced with a custom agent.","messagePattern":"Built-in Subconscious reflection agent \"(.+?)\" cannot be replaced with a custom agent\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/index.ts","lineNumber":230,"sourceCode":"    }\n    if ('model' in entry || 'maxSteps' in entry) {\n      throw new Error(\n        `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 {","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/index.ts#L212-L248","documentation":"Built-in reflection agents encapsulate curated prompts/agents. If an entry names a built-in (per BUILT_IN_REFLECTION) but also supplies a custom 'agent', the library rejects it — you may not swap a built-in's implementation while keeping its name.","triggerScenarios":"new Subconscious({ reflection: [{ name: 'insight', agent: myAgent }] }) where 'insight' is a built-in reflection name and entry.agent is truthy.","commonSituations":"Trying to override a built-in's model/behavior by attaching a custom agent; copy-pasted config where agent leaked into a built-in entry; assuming built-ins are just defaults that can be replaced in place.","solutions":["Remove the agent property from the built-in entry.","Rename the entry to a custom name with { name: 'my-reflection', agent: myAgent } or { instructions: ... }.","Use built-in names only as bare strings if you want stock behavior."],"exampleFix":"// before\nnew Subconscious({ reflection: [{ name: 'insight', agent: myAgent }] });\n// after\nnew Subconscious({ reflection: [{ name: 'custom-insight', agent: myAgent }] });","handlingStrategy":"validation","validationCode":"const entry = { name: 'insight', agent: myAgent };\nif (BUILT_IN_REFLECTION.has(entry.name) && 'agent' in entry) {\n  throw new Error('built-in reflection entries cannot carry a custom agent; rename the entry');\n}","typeGuard":"function isCustomReflectionEntry(e: { name: string; agent?: unknown }): boolean {\n  return !BUILT_IN_REFLECTION.has(e.name) || !e.agent;\n}","tryCatchPattern":"try {\n  sub = new Subconscious({ reflection: [entry] });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('cannot be replaced with a custom agent')) {\n    entry = { ...entry, name: `custom-${entry.name}` };\n    sub = new Subconscious({ reflection: [entry] });\n  } else throw e;\n}","preventionTips":["Reserve built-in names for string entries only.","Prefix custom reflection names (e.g. 'custom-') to avoid collisions.","Type reflection entries with a discriminated union of built-in | custom."],"tags":["configuration","validation","observational-memory"],"backgroundTag":"invalid-configuration-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}