{"record":{"id":"d58e179e9593a1ea","repo":"mastra-ai/mastra","slug":"node-descriptions-are-limited-to-max-knowledge-n","errorCode":null,"errorMessage":"Node descriptions are limited to ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units. Shorten the description and retry.","messagePattern":"Node descriptions are limited to (.+?) UTF-16 code units\\. Shorten the description and retry\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts","lineNumber":202,"sourceCode":"        type: 'object',\n        properties: {\n          node: { type: 'string', minLength: 1 },\n          expectedVersion: { type: 'integer', minimum: 1 },\n          description: {\n            type: 'string',\n            minLength: 0,\n            maxLength: MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH,\n            description: `One or two plain-text sentences describing the node, targeting 40-75 tokens. Hard limit ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units, enforced by storage on every write; the length check on execution is authoritative. Long-form detail belongs in node content, not here. An empty string clears the description.`,\n          },\n        },\n        required: ['node', 'expectedVersion', 'description'],\n        additionalProperties: false,\n      } satisfies JSONSchema7,\n      execute: async input => {\n        const value = input as { node: string; expectedVersion: number; description: string };\n        // Schema maxLength counts code points; this UTF-16 check is authoritative (same pattern as the capture-guidance bound above).\n        if (value.description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {\n          throw new Error(\n            `Node descriptions are limited to ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units. Shorten the description and retry.`,\n          );\n        }\n        const store = await getStore(memory);\n        const node = await store.getNode(value.node);\n        if (!node || node.mergedInto) throw new Error(`Knowledge node not found: ${value.node}`);\n        requireVisible(node.scope, options, 'Knowledge node');\n        return store.updateNode({\n          id: node.id,\n          version: value.expectedVersion,\n          description: value.description,\n        });\n      },\n    }),\n    knowledge_write_node_content: createTool({\n      id: 'knowledge_write_node_content',\n      description:\n        'Create or replace long-form content on a scoped knowledge node. Existing nodes require expectedVersion.',","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/knowledge-write-tools.ts#L184-L220","documentation":"The knowledge_update_node tool enforces a hard cap on node description length measured in UTF-16 code units (JavaScript string.length). This runtime check exists because JSON Schema maxLength counts code points, which can under-count astral characters (e.g. emoji), so the UTF-16 check is authoritative. Exceeding MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH throws this error before any storage write.","triggerScenarios":"Calling knowledge_update_node with a description whose .length exceeds the limit — most commonly when the description contains many multi-code-unit characters (emoji, CJK extensions) that slipped past the schema maxLength.","commonSituations":"LLM-generated descriptions that are verbose or emoji-heavy; concatenating summaries without truncation; inputs near the schema limit that differ between code-point and UTF-16 counting.","solutions":["Shorten the description below MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH UTF-16 code units and retry the tool call","Truncate programmatically with Array.from(description).slice(0, max).join('') after checking description.length","Remove emoji/surrogate-pair characters which consume two UTF-16 code units each"],"exampleFix":"// before\nawait tool.execute({ node, expectedVersion, description: longSummary });\n// after\nconst max = MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH;\nconst description = longSummary.length > max ? longSummary.slice(0, max) : longSummary;\nawait tool.execute({ node, expectedVersion, description });","handlingStrategy":"validation","validationCode":"import { MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH } from '@mastra/core/storage';\nif (description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {\n  description = description.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await tool.execute({ node, expectedVersion, description });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('UTF-16 code units')) {\n    await tool.execute({ node, expectedVersion, description: description.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) });\n  } else throw e;\n}","preventionTips":["Check .length (UTF-16 units), not code points, when pre-truncating","Strip emoji/astral characters from generated descriptions","Keep node descriptions concise by design"],"tags":["validation","string-length","memory"],"backgroundTag":"input-length-limit-exceeded","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}