mastra-ai/mastra · error

Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_

Error message

Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code unit limit

What it means

KnowledgeNode.description is a bounded synopsis (max 400 UTF-16 code units) rendered into list/graph payloads; the bound is part of the storage contract enforced in createNode and updateNode by every adapter via assertKnowledgeDescriptionWithinBound. A longer description is rejected before the write, leaving the existing node untouched and its version unincremented. Long-form content belongs in the content field.

Source

Thrown at packages/core/src/storage/domains/knowledge/base.ts:354

 * `description` is a concise synopsis rendered into graph and list payloads, potentially across
 * hundreds of nodes at once, so the bound belongs to the storage contract rather than to any one
 * writer: every adapter enforces it in `createNode` and `updateNode` regardless of which tool
 * performs the write. Long-form detail stays in {@link KnowledgeNode.content}.
 *
 * @experimental
 */
export const MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH = 400;

/**
 * Rejects an over-long node description before any write occurs, so an oversized update leaves the
 * existing node untouched and does not increment its version.
 *
 * @experimental
 */
export function assertKnowledgeDescriptionWithinBound(description: string | undefined): void {
  if (description === undefined) return;
  if (description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {
    throw new Error(
      `Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code unit limit`,
    );
  }
}

export function assertKnowledgeScopeWithinCeiling(scope: KnowledgeScope, maxScope?: KnowledgeScopeLevel): void {
  if (!maxScope) return;
  const reservedLevels = scope
    .map(entry => SCOPE_ORDER[entry.slice(0, entry.indexOf(':')) as KnowledgeScopeLevel])
    .filter((value): value is number => value !== undefined);
  const narrowestLevel = reservedLevels.length > 0 ? Math.max(...reservedLevels) : Number.MAX_SAFE_INTEGER;
  if (narrowestLevel < SCOPE_ORDER[maxScope]) {
    throw new Error(`Knowledge scope exceeds ${maxScope} ceiling`);
  }
}

export function assertKnowledgeCeilingRaised(
  currentMaxScope: KnowledgeScopeLevel | undefined,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Truncate or summarize the description to <= 400 UTF-16 code units before writing (use .slice(0, 400)).
2. Move long detail into the node's content field, keeping description a short synopsis.
3. Pre-validate with the exported assertKnowledgeDescriptionWithinBound or description.length <= MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH.
4. Instruct generating agents/models with an explicit 400-character limit in their prompt/tool schema.

Example fix

// before
await storage.createNode({ name, kind, scope, description: longSummary });
// after
const description = longSummary.length > 400 ? longSummary.slice(0, 397) + '...' : longSummary;
await storage.createNode({ name, kind, scope, description, content: longSummary });

import { MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH, assertKnowledgeDescriptionWithinBound } from '@mastra/core/storage';
function clampDescription(d?: string): string | undefined {
  if (d === undefined) return undefined;
  return d.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH ? d.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) : d;
}

When it happens

Trigger: createNode({ description: <401+ char string> }) or updateNode({ id, version, description: <401+ chars> }); AI/tool-generated descriptions pasted verbatim from long summaries; descriptions copied from content.

Common situations: LLM writing verbose node synopses without length control; users pasting paragraphs into a description field in a UI; locale-specific text assumed shorter; confusing description with content.

Related errors

• Invalid knowledge node cursor.
• Knowledge node cursor does not match the active browse filte
• Invalid knowledge scope entry: ${entry}
• Knowledge scope contains multiple ${level} entries
• Knowledge scope cannot be empty

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