mastra-ai/mastra · error · Error

knowledge_update_node requires at least one of: name, kind.

Error message

knowledge_update_node requires at least one of: name, kind.

What it means

knowledge_update_node performs an optimistic-concurrency update of a node's name and/or kind. Because both fields are optional in the schema, the execute handler explicitly rejects calls where neither is present — a no-op update — with this error. It guarantees every update call carries at least one field to change.

Source

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

    knowledge_update_node: createTool({
      id: 'knowledge_update_node',
      description:
        'Update a visible node name or kind using optimistic concurrency. Provide at least one of name or kind.',
      inputSchema: {
        type: 'object',
        properties: {
          node: { type: 'string', minLength: 1 },
          expectedVersion: { type: 'integer', minimum: 1 },
          name: { type: 'string', minLength: 1 },
          kind: { type: 'string', minLength: 1 },
        },
        required: ['node', 'expectedVersion'],
        additionalProperties: false,
      } satisfies JSONSchema7,
      execute: async input => {
        const value = input as { node: string; expectedVersion: number; name?: string; kind?: string };
        if (value.name === undefined && value.kind === undefined) {
          throw new Error('knowledge_update_node requires at least one of: name, kind.');
        }
        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,
          name: value.name,
          kind: value.kind,
        });
      },
    }),
    knowledge_merge_nodes: createTool({
      id: 'knowledge_merge_nodes',
      description: 'Merge a visible duplicate node into another visible node using source-version CAS.',
      inputSchema: {
        type: 'object',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include name and/or kind in the call alongside node and expectedVersion.
2. If nothing should change, don't call the update tool at all.
3. Add agent instructions: every knowledge_update_node call must carry at least one of name, kind.
4. In wrappers, assert (value.name !== undefined || value.kind !== undefined) before execute().

Example fix

// before
await tools.knowledge_update_node.execute({ node: 'node_1', expectedVersion: 3 }, ctx);
// after
await tools.knowledge_update_node.execute({ node: 'node_1', expectedVersion: 3, name: 'Renamed Node' }, ctx);

type UpdateArgs = { node: string; expectedVersion: number; name?: string; kind?: string };
if (args.name === undefined && args.kind === undefined) {
  throw new Error('knowledge_update_node needs name or kind');
}

function hasUpdateField(a: unknown): a is { node: string; expectedVersion: number } & ({ name: string } | { kind: string }) {
  const x = a as { name?: unknown; kind?: unknown };
  return x?.name !== undefined || x?.kind !== undefined;
}

try {
  return await curatorTools.knowledge_update_node.execute(args, {} as any);
} catch (e) {
  if (e instanceof Error && e.message === 'knowledge_update_node requires at least one of: name, kind.') {
    return { updated: false, reason: 'no-op-update' };
  }
  throw e;
}

When it happens

Trigger: Agent calls knowledge_update_node passing only node and expectedVersion (both name and kind omitted), e.g. attempting a 'touch' or retrying a failed update without re-including fields.

Common situations: LLM retries after a version conflict while dropping the name/kind fields; prompt templates showing only required schema fields; programmatic scripts forwarding partial payloads.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• knowledge_read requires id or name.
• Factory rule version is required.
• MISSING_ARGUMENT
• No project specified. Pass --project <name|slug|id>, set MAS
• AGENT_SEND_STREAM_RESUME_MISSING_TARGET

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