mastra-ai/mastra · error · Error

knowledge_read requires id or name.

Error message

knowledge_read requires id or name.

What it means

The knowledge_read tool fetches a single node either by its ID or by resolving its name within the caller's scope. Because the input schema leaves both optional, the execute handler performs an explicit check and throws when neither is provided, since there would be no way to identify the node. This is a tool-input validation error, typically raised when the LLM calls the tool with an empty or malformed arguments object.

Source

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

        limit: { type: 'integer', minimum: 1, maximum: MAX_LIMIT },
      },
      additionalProperties: false,
    } satisfies JSONSchema7,
    execute: async (input, context) => {
      const {
        id,
        name,
        relationship = 'about',
        cursor,
        limit: requestedLimit,
      } = input as {
        id?: string;
        name?: string;
        relationship?: 'about' | 'mentioning' | 'related';
        cursor?: string;
        limit?: number;
      };
      if (!id && !name) throw new Error('knowledge_read requires id or name.');
      const scope = fixedScope ?? resolveScope(context as KnowledgeToolContext);
      const store = await getKnowledgeStore(memory);
      const node = id ? await store.getNode(id) : await store.resolveNode({ name: name!, scope });
      if (!node || node.mergedInto || !isKnowledgeScopeVisible(node.scope, scope)) return { found: false };
      const query =
        relationship === 'related'
          ? store.listKnowledgeRelatedTo
          : relationship === 'mentioning'
            ? store.listKnowledgeMentioning
            : store.listKnowledgeAbout;
      const result = await query.call(store, {
        node,
        scope,
        after: cursor,
        limit: normalizeLimit(requestedLimit),
      });
      return {
        found: true,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include either id (node ID) or name (resolvable node name) in the knowledge_read input.
2. If the node is known by name only, pass name and ensure it resolves within the caller's scope.
3. Strengthen the tool description / agent instructions so the model always supplies id or name.
4. In programmatic callers, validate the args object before execute().

Example fix

// before
await tools.knowledge_read.execute({ limit: 5 }, ctx);
// after
await tools.knowledge_read.execute({ id: 'node_abc' }, ctx); // or { name: 'Deployment Guide' }

type ReadArgs = { id?: string; name?: string; relationship?: string; cursor?: string; limit?: number };
function canRead(args: ReadArgs): boolean {
  return typeof args.id === 'string' || typeof args.name === 'string';
}
if (!canRead(args)) throw new Error('knowledge_read needs id or name');

function hasReadSelector(a: unknown): a is { id: string } | { name: string } {
  const x = a as { id?: unknown; name?: unknown };
  return typeof x?.id === 'string' || typeof x?.name === 'string';
}

try {
  return await tools.knowledge_read.execute(args, ctx);
} catch (e) {
  if (e instanceof Error && e.message === 'knowledge_read requires id or name.') {
    return { found: false, reason: 'missing-selector' };
  }
  throw e;
}

When it happens

Trigger: The curator/learner agent calls knowledge_read with arguments {} or only optional fields (relationship, cursor, limit), omitting both id and name.

Common situations: LLM hallucinating a call with no selectors; prompt templates that under-specify the tool's arguments; programmatic tool invocations that pass an empty object.

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_update_node requires at least one of: name, kind.
• 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/4239852ecab03692. Report an issue: GitHub.