mastra-ai/mastra · error · Error

Custom Subconscious reflection agent "${name}" requires inst

Error message

Custom Subconscious reflection agent "${name}" requires instructions or agent.

What it means

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.

Source

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

        `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 {
  createPinnedTools,
  listPinnedKnowledge,
  DEFAULT_MAX_PINS,

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
new Subconscious({ reflection: [{ name: 'weekly-review' }] });
// after
new Subconscious({ reflection: [{ name: 'weekly-review', instructions: 'Review the week observations and summarize progress.' }] });

Defensive patterns

Strategy: validation

Validate before calling

const entry = { name: 'weekly-review', instructions: process.env.REVIEW_INSTRUCTIONS ?? '' };
if (!BUILT_IN_REFLECTION.has(entry.name) && !entry.instructions.trim() && !('agent' in entry)) {
  throw new Error(`Reflection '${entry.name}' needs instructions or agent`);
}

Type guard

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

Try / catch

try {
  sub = new Subconscious({ reflection: [entry] });
} catch (e) {
  if (e instanceof Error && e.message.includes('requires instructions or agent')) {
    console.error(`Reflection '${entry.name}' has no behavior defined`);
  } else throw e;
}

Prevention

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.

When it happens

Trigger: new Subconscious({ reflection: [{ name: 'my-reflection' }] }), or instructions: ' ' (whitespace-only, caught by .trim()) with no agent key.

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

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

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