mastra-ai/mastra · error · Error

capture-guidance is limited to ${MAX_GUIDANCE_LENGTH} charac

Error message

capture-guidance is limited to ${MAX_GUIDANCE_LENGTH} characters.

What it means

When creating/updating the special 'capture-guidance' node (name is case-insensitively reserved), the content length is capped at MAX_GUIDANCE_LENGTH (4000) characters. This node injects instructions into capture prompts, so unbounded content would bloat every capture. The error is thrown before any storage call when a capture-guidance write exceeds the cap.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts:245

          scope: scopeLevelSchema,
          expectedVersion: { type: 'integer', minimum: 1 },
        },
        required: ['name', 'content'],
        additionalProperties: false,
      } satisfies JSONSchema7,
      execute: async input => {
        const value = input as {
          name: string;
          kind?: string;
          content: string;
          scope?: KnowledgeScopeLevel;
          expectedVersion?: number;
        };
        const trimmedName = value.name.trim();
        const reservedName = trimmedName.toLowerCase();
        const name = reservedName === 'capture-guidance' ? reservedName : trimmedName;
        if (reservedName === 'capture-guidance' && value.content.length > MAX_GUIDANCE_LENGTH) {
          throw new Error(`capture-guidance is limited to ${MAX_GUIDANCE_LENGTH} characters.`);
        }
        const store = await getStore(memory);
        const scope = resolveWriteScope(options, value.scope);
        const resolvedNode = await store.resolveNode({ name, scope });
        const existing =
          resolvedNode && knowledgeScopeKey(resolvedNode.scope) === knowledgeScopeKey(scope) ? resolvedNode : null;
        if (!existing) {
          if (value.expectedVersion !== undefined)
            throw new Error('expectedVersion is only valid for an existing node.');
          return store.createNode({
            name,
            kind: value.kind ?? 'document',
            content: value.content,
            scope,
            resolutionScope: options.scope,
          });
        }
        if (value.expectedVersion === undefined) throw new Error('Updating node content requires expectedVersion.');

View on GitHub (pinned to 75dd419e61)

Solutions

Shorten the capture-guidance content to 4000 characters or fewer and retry
Split content into concise bullet rules and drop redundant guidance
Pre-check value.content.length before the call and truncate or reject oversized guidance in your own tooling

Example fix

// before
await tool.execute({ name: 'capture-guidance', content: longInstructions, scope: 'org' });
// after
const content = longInstructions.length > 4000 ? longInstructions.slice(0, 4000) : longInstructions;
await tool.execute({ name: 'capture-guidance', content, scope: 'org' });

Defensive patterns

Strategy: validation

Validate before calling

if (name.trim().toLowerCase() === 'capture-guidance' && content.length > 4000) {
  content = content.slice(0, 4000);
}

Try / catch

try {
  await tool.execute({ name, content, scope });
} catch (e) {
  if (e instanceof Error && e.message.includes('capture-guidance is limited')) {
    await tool.execute({ name, content: content.slice(0, 4000), scope });
  } else throw e;
}

Prevention

Keep capture-guidance under 4000 characters by writing terse rules
Enforce the limit in whatever UI/code lets users edit guidance
Periodically prune stale guidance entries

When it happens

Trigger: Calling the node upsert tool with name 'capture-guidance' (any casing, trimmed) and content longer than 4000 characters.

Common situations: Long operating instructions pasted wholesale into guidance; cumulative guidance growth without pruning; LLM generating verbose guidance text.

Related errors

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