What causes "Unknown Subconscious reflection agent: ${name}" in mastra-ai/mastra?

Correct the string to a valid built-in reflection name (see BUILT_IN_REFLECTION in the subconscious module).

mastra-ai/mastra · error · Error

Unknown Subconscious reflection agent: ${name}

Error message

Unknown Subconscious reflection agent: ${name}

What it means

Reflection entries given as plain strings must name a built-in reflection agent tracked in BUILT_IN_REFLECTION. An unknown string name fails constructor validation immediately, mirroring the observation-side check for reflection.

Source

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

          throw new Error('A custom capture schema requires an onExtracted hook that handles its output.');
        }
      }
      return;
    }
    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';

View on GitHub (pinned to 75dd419e61)

Solutions

Correct the string to a valid built-in reflection name (see BUILT_IN_REFLECTION in the subconscious module).
Use an object entry ({ instructions: ... } or { agent: ... }) for custom reflection behavior.
Align the installed @mastra/memory version with the docs you followed.

Example fix

// before
new Subconscious({ reflection: ['insite'] });
// after
new Subconscious({ reflection: ['insight'] }); // valid built-in, or a custom object entry

Defensive patterns

Strategy: validation

Validate before calling

const reflection = ['insight'];
const bad = reflection.filter(r => typeof r === 'string' && !BUILT_IN_REFLECTION.has(r));
if (bad.length) throw new Error(`Unknown reflection agents: ${bad.join(', ')}`);

Type guard

function isBuiltInReflection(name: string): boolean {
  return BUILT_IN_REFLECTION.has(name);
}

Try / catch

try {
  sub = new Subconscious({ reflection: names });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown Subconscious reflection agent')) {
    console.error(`Invalid reflection entry: ${e.message}`);
  } else throw e;
}

Prevention

Use the exported built-in reflection name union type.
Keep observation and reflection name lists separate to avoid cross-use.
Construct Subconscious in a unit test with production config.
Diff your names against BUILT_IN_REFLECTION after version upgrades.

When it happens

Trigger: new Subconscious({ reflection: ['summariez'] }) or any reflection string not present in BUILT_IN_REFLECTION.

Common situations: Typo in a built-in reflection name; using an observation-agent name in the reflection list; version mismatch where a documented built-in reflection name does not exist in the installed package.

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/1eac8db5c6cfa3c3. Report an issue: GitHub.