mastra-ai/mastra · error · Error

Subconscious ${phase} agent name is required.

Error message

Subconscious ${phase} agent name is required.

What it means

The Subconscious constructor validates that every observation/reflection agent entry (string name or config object) has a non-empty name via assertUniqueNames. An entry without a name cannot be addressed or deduplicated, so the constructor throws early. This is a fail-fast config validation.

Source

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

/**
 * Curation walks a worklist that can reach hundreds of records, and its completion marker is
 * fail-closed: a curator that runs out of steps advances no cursor at all. It gets a much larger
 * default budget than the other agents, which each handle a single bounded prompt.
 */
const DEFAULT_MAX_STEPS_BY_AGENT: Record<string, number> = { curate: 200 };
const MAX_MAX_STEPS = 500;
const DEFAULT_RECENT_UPDATES = 10;
const MAX_RECENT_UPDATES = 100;

function entryName(entry: string | { name: string }): string {
  return typeof entry === 'string' ? entry : entry.name.trim();
}

function assertUniqueNames(entries: Array<string | { name: string }>, phase: string): void {
  const seen = new Set<string>();
  for (const entry of entries) {
    const name = entryName(entry);
    if (!name) throw new Error(`Subconscious ${phase} agent name is required.`);
    if (seen.has(name)) throw new Error(`Duplicate Subconscious ${phase} agent: ${name}`);
    seen.add(name);
  }
}

function boundedSteps(entry: { maxSteps?: number } | undefined, fallback: number): number {
  const steps = entry?.maxSteps ?? fallback;
  if (!Number.isInteger(steps) || steps < 1 || steps > MAX_MAX_STEPS) {
    throw new Error(`Subconscious maxSteps must be an integer between 1 and ${MAX_MAX_STEPS}.`);
  }
  return steps;
}

function resolveExtractor(entry: SubconsciousObservationEntry): ResolvedSubconsciousAgent {
  const config = typeof entry === 'string' ? undefined : entry;
  const name = entryName(entry);
  return {
    name,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Give every observation/reflection entry a name: either a plain string or an object with a non-empty name property.
2. Validate config objects before constructing Subconscious.
3. Use string shorthand entries when no per-agent options are needed.

Example fix

// before
new Subconscious({ observation: [{ maxSteps: 5 }] })
// after
new Subconscious({ observation: [{ name: 'observer', maxSteps: 5 }] })

for (const e of [...observation, ...reflection]) {
  const name = typeof e === 'string' ? e : e?.name;
  if (!name) throw new Error('Every Subconscious agent entry needs a non-empty name');
}

function isNamedEntry(e: unknown): e is { name: string } & Record<string, unknown> {
  return typeof e === 'object' && e !== null && typeof (e as { name?: unknown }).name === 'string' && (e as { name: string }).name.trim().length > 0;
}

try {
  const sub = new Subconscious(config);
} catch (err) {
  if (err.message.includes('agent name is required')) {
    throw new ConfigError('Invalid Subconscious config: an observation/reflection entry is missing a name');
  } else throw err;
}

When it happens

Trigger: Passing a Subconscious observation or reflection entry as an object with name: undefined/'' (e.g. { maxSteps: 5 } or { model } only) instead of a string or a named config.

Common situations: Copy-pasting an agent entry and deleting the name field; programmatically building entries where a lookup for the name fails; renaming an agent and leaving an empty string.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Subconscious semantic knowledge requires a vector store. Pas
• Subconscious semantic knowledge requires an embedder. Pass a
• Duplicate Subconscious ${phase} agent: ${name}
• Subconscious maxSteps must be an integer between 1 and ${MAX
• Subconscious activity.recentUpdates must be an integer betwe

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