{"record":{"id":"69f320677863badd","repo":"mastra-ai/mastra","slug":"knowledge-node-description-exceeds-the-max-knowl","errorCode":null,"errorMessage":"Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code unit limit","messagePattern":"Knowledge node description exceeds the (.+?) UTF-16 code unit limit","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/knowledge/base.ts","lineNumber":354,"sourceCode":" * `description` is a concise synopsis rendered into graph and list payloads, potentially across\n * hundreds of nodes at once, so the bound belongs to the storage contract rather than to any one\n * writer: every adapter enforces it in `createNode` and `updateNode` regardless of which tool\n * performs the write. Long-form detail stays in {@link KnowledgeNode.content}.\n *\n * @experimental\n */\nexport const MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH = 400;\n\n/**\n * Rejects an over-long node description before any write occurs, so an oversized update leaves the\n * existing node untouched and does not increment its version.\n *\n * @experimental\n */\nexport function assertKnowledgeDescriptionWithinBound(description: string | undefined): void {\n  if (description === undefined) return;\n  if (description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {\n    throw new Error(\n      `Knowledge node description exceeds the ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code unit limit`,\n    );\n  }\n}\n\nexport function assertKnowledgeScopeWithinCeiling(scope: KnowledgeScope, maxScope?: KnowledgeScopeLevel): void {\n  if (!maxScope) return;\n  const reservedLevels = scope\n    .map(entry => SCOPE_ORDER[entry.slice(0, entry.indexOf(':')) as KnowledgeScopeLevel])\n    .filter((value): value is number => value !== undefined);\n  const narrowestLevel = reservedLevels.length > 0 ? Math.max(...reservedLevels) : Number.MAX_SAFE_INTEGER;\n  if (narrowestLevel < SCOPE_ORDER[maxScope]) {\n    throw new Error(`Knowledge scope exceeds ${maxScope} ceiling`);\n  }\n}\n\nexport function assertKnowledgeCeilingRaised(\n  currentMaxScope: KnowledgeScopeLevel | undefined,","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/knowledge/base.ts#L336-L372","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Truncate or summarize the description to <= 400 UTF-16 code units before writing (use .slice(0, 400)).","Move long detail into the node's content field, keeping description a short synopsis.","Pre-validate with the exported assertKnowledgeDescriptionWithinBound or description.length <= MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH.","Instruct generating agents/models with an explicit 400-character limit in their prompt/tool schema."],"exampleFix":"// before\nawait storage.createNode({ name, kind, scope, description: longSummary });\n// after\nconst description = longSummary.length > 400 ? longSummary.slice(0, 397) + '...' : longSummary;\nawait storage.createNode({ name, kind, scope, description, content: longSummary });","handlingStrategy":"validation","validationCode":"import { MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH, assertKnowledgeDescriptionWithinBound } from '@mastra/core/storage';\nfunction clampDescription(d?: string): string | undefined {\n  if (d === undefined) return undefined;\n  return d.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH ? d.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) : d;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp or summarize descriptions before every createNode/updateNode.","Put long text in content, keep description <= 400 UTF-16 code units.","Constrain generating models/tool schemas to a 400-char description limit.","Remember .length counts UTF-16 code units, matching the library's check."],"tags":["knowledge","validation","length-limit","write-rejected"],"backgroundTag":"string-length-limit-exceeded","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}