mastra-ai/mastra · error · Error

Unknown Subconscious observation agent: ${name}

Error message

Unknown Subconscious observation agent: ${name}

What it means

The Subconscious processor accepts observation entries either as built-in agent names (strings) or custom extractor objects. When a plain string is given, it must be one of the known built-in observation agent names tracked in BUILT_IN_OBSERVATION; otherwise the constructor throws immediately during validation. This fails fast on configuration mistakes rather than at runtime.

Source

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

        extractors.push(
          new Extractor({
            name: custom.name,
            instructions: custom.instructions?.trim() || `Extract ${custom.name} from the current observations.`,
            schema: custom.schema,
            metadataKeyPath: false,
            includePreviousExtraction: false,
            onExtracted: custom.onExtracted,
          }),
        );
      }
    }
    return extractors;
  }

  #validateObservationEntry(entry: SubconsciousObservationEntry): void {
    const name = entryName(entry);
    if (typeof entry === 'string') {
      if (!BUILT_IN_OBSERVATION.has(name)) throw new Error(`Unknown Subconscious observation agent: ${name}`);
      return;
    }
    if (BUILT_IN_OBSERVATION.has(name)) {
      if (name === 'capture') {
        if ('model' in entry || 'maxSteps' in entry) {
          throw new Error('Subconscious capture 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('A custom capture schema requires an onExtracted hook that handles its output.');
        }
      }
      return;
    }
    if ('model' in entry || 'maxSteps' in entry) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the allowed built-in observation names in BUILT_IN_OBSERVATION (constants/types in packages/memory/src/processors/observational-memory/subconscious) and correct the spelling.
2. If you want a custom extractor, pass an object with schema and onExtracted instead of a bare string.
3. Pin/align the @mastra/memory version so documented built-in names match the installed code.

Example fix

// before
new Subconscious({ observation: ['summarizer'] });
// after
new Subconscious({ observation: ['capture'] }); // valid built-in, or an object entry
new Subconscious({ observation: [{ name: 'summarizer', schema: MySchema, onExtracted: async (r) => r }]);

import { BUILT_IN_OBSERVATION } from './subconscious/constants';
const observation = ['capture'];
const invalid = observation.filter(o => typeof o === 'string' && !BUILT_IN_OBSERVATION.has(o));
if (invalid.length) throw new Error(`Unknown observation agents: ${invalid.join(', ')}`);

function isBuiltInObservation(name: string): boolean {
  return BUILT_IN_OBSERVATION.has(name);
}

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

When it happens

Trigger: Passing new Subconscious({...observation: ['captre']...}) or any string entry in the observation array that is not in BUILT_IN_OBSERVATION. Thrown synchronously from #validateObservationEntry during construction.

Common situations: Typo in a built-in agent name; copying a reflection-agent name into the observation list; upgrading/downgrading the library where the set of built-in names changed; assuming arbitrary custom names are allowed as strings instead of objects.

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

• observationalMemory.experimental_subconscious must be a Subc
• `retrieval: { vector: true }` requires a vector store. Pass
• `retrieval: { vector: true }` requires an embedder. Pass an
• observation.bufferTokens must be > 0, got ${this.observation
• observation.bufferTokens (${this.observationConfig.bufferTok

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