mastra-ai/mastra · error · Error

Built-in Subconscious reflection agent "${name}" cannot be r

Error message

Built-in Subconscious reflection agent "${name}" cannot be replaced with a custom agent.

What it means

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.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/index.ts:230

    }
    if ('model' in entry || 'maxSteps' in entry) {
      throw new Error(
        `Subconscious observation extractor "${name}" shares the Observer model and does not accept model or maxSteps.`,
      );
    }
    if (!('schema' in entry) || !entry.schema || !('onExtracted' in entry) || typeof entry.onExtracted !== 'function') {
      throw new Error(`Custom Subconscious observation agent "${name}" requires schema and onExtracted.`);
    }
  }

  #validateReflectionEntry(entry: SubconsciousReflectionEntry): void {
    const name = entryName(entry);
    if (typeof entry === 'string') {
      if (!BUILT_IN_REFLECTION.has(name)) throw new Error(`Unknown Subconscious reflection agent: ${name}`);
      return;
    }
    if (BUILT_IN_REFLECTION.has(name) && 'agent' in entry && entry.agent) {
      throw new Error(`Built-in Subconscious reflection agent "${name}" cannot be replaced with a custom agent.`);
    }
    if (!BUILT_IN_REFLECTION.has(name) && !entry.instructions?.trim() && !('agent' in entry && entry.agent)) {
      throw new Error(`Custom Subconscious reflection agent "${name}" requires instructions or agent.`);
    }
  }
}

export {
  buildSubconsciousActivitySnapshot,
  publishSubconsciousActivity,
  publishSubconsciousError,
  renderSubconsciousActivity,
  SUBCONSCIOUS_ACTIVITY_STATE_ID,
} from './activity';
export type { SubconsciousActivitySnapshot, SubconsciousActivityUpdate } from './activity';
export { SubconsciousCaptureExtractor, subconsciousCaptureSchema } from './capture';
export { SubconsciousRemindExtractor } from './remind';
export {

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
new Subconscious({ reflection: [{ name: 'insight', agent: myAgent }] });
// after
new Subconscious({ reflection: [{ name: 'custom-insight', agent: myAgent }] });

Defensive patterns

Strategy: validation

Validate before calling

const entry = { name: 'insight', agent: myAgent };
if (BUILT_IN_REFLECTION.has(entry.name) && 'agent' in entry) {
  throw new Error('built-in reflection entries cannot carry a custom agent; rename the entry');
}

Type guard

function isCustomReflectionEntry(e: { name: string; agent?: unknown }): boolean {
  return !BUILT_IN_REFLECTION.has(e.name) || !e.agent;
}

Try / catch

try {
  sub = new Subconscious({ reflection: [entry] });
} catch (e) {
  if (e instanceof Error && e.message.includes('cannot be replaced with a custom agent')) {
    entry = { ...entry, name: `custom-${entry.name}` };
    sub = new Subconscious({ reflection: [entry] });
  } else throw e;
}

Prevention

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.

When it happens

Trigger: new Subconscious({ reflection: [{ name: 'insight', agent: myAgent }] }) where 'insight' is a built-in reflection name and entry.agent is truthy.

Common situations: 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.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

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