mastra-ai/mastra · error · Error

Node descriptions are limited to ${MAX_KNOWLEDGE_NODE_DESCRI

Error message

Node descriptions are limited to ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units. Shorten the description and retry.

What it means

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.

Source

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

        type: 'object',
        properties: {
          node: { type: 'string', minLength: 1 },
          expectedVersion: { type: 'integer', minimum: 1 },
          description: {
            type: 'string',
            minLength: 0,
            maxLength: MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH,
            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.`,
          },
        },
        required: ['node', 'expectedVersion', 'description'],
        additionalProperties: false,
      } satisfies JSONSchema7,
      execute: async input => {
        const value = input as { node: string; expectedVersion: number; description: string };
        // Schema maxLength counts code points; this UTF-16 check is authoritative (same pattern as the capture-guidance bound above).
        if (value.description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {
          throw new Error(
            `Node descriptions are limited to ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units. Shorten the description and retry.`,
          );
        }
        const store = await getStore(memory);
        const node = await store.getNode(value.node);
        if (!node || node.mergedInto) throw new Error(`Knowledge node not found: ${value.node}`);
        requireVisible(node.scope, options, 'Knowledge node');
        return store.updateNode({
          id: node.id,
          version: value.expectedVersion,
          description: value.description,
        });
      },
    }),
    knowledge_write_node_content: createTool({
      id: 'knowledge_write_node_content',
      description:
        'Create or replace long-form content on a scoped knowledge node. Existing nodes require expectedVersion.',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Shorten the description below MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH UTF-16 code units and retry the tool call
2. Truncate programmatically with Array.from(description).slice(0, max).join('') after checking description.length
3. Remove emoji/surrogate-pair characters which consume two UTF-16 code units each

Example fix

// before
await tool.execute({ node, expectedVersion, description: longSummary });
// after
const max = MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH;
const description = longSummary.length > max ? longSummary.slice(0, max) : longSummary;
await tool.execute({ node, expectedVersion, description });

import { MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH } from '@mastra/core/storage';
if (description.length > MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) {
  description = description.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH);
}

try {
  await tool.execute({ node, expectedVersion, description });
} catch (e) {
  if (e instanceof Error && e.message.includes('UTF-16 code units')) {
    await tool.execute({ node, expectedVersion, description: description.slice(0, MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH) });
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• capture-guidance is limited to ${MAX_GUIDANCE_LENGTH} charac
• MastraClient.deleteThread() requires exactly one of agentId
• Thread ID is required for thread-scoped working memory updat
• Resource ID is required for resource-scoped working memory u
• Thread with id ${threadId} resourceId does not match the cur

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