mastra-ai/mastra · error · Error

KnowledgeRecord not found: ${value.recordId}

Error message

KnowledgeRecord not found: ${value.recordId}

What it means

The knowledge_rescope tool looks up the knowledge record by recordId before changing its scope. If no record with that ID exists in the knowledge storage domain, this error is thrown. The library checks existence (and later visibility and scope ceiling) so it never silently rewrites or creates records.

Source

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

        requireVisible(source.scope, options, 'Knowledge merge source');
        requireVisible(target.scope, options, 'Knowledge merge target');
        return store.mergeNodes(value);
      },
    }),
    knowledge_rescope: createTool({
      id: 'knowledge_rescope',
      description: 'Change a record visibility scope without exceeding its stamped ceiling.',
      inputSchema: {
        type: 'object',
        properties: { recordId: { type: 'string', minLength: 1 }, scope: scopeLevelSchema },
        required: ['recordId', 'scope'],
        additionalProperties: false,
      } satisfies JSONSchema7,
      execute: async input => {
        const value = input as { recordId: string; scope: KnowledgeScopeLevel };
        const store = await getStore(memory);
        const record = await store.getKnowledge({ id: value.recordId });
        if (!record) throw new Error(`KnowledgeRecord not found: ${value.recordId}`);
        requireVisible(record.scope, options, 'KnowledgeRecord');
        const scope = resolveWriteScope(options, value.scope);
        assertKnowledgeScopeWithinCeiling(scope, record.maxScope);
        return store.rescopeKnowledge({ id: record.id, scope });
      },
    }),
    knowledge_write_node_description: createTool({
      id: 'knowledge_write_node_description',
      description: `Write the bounded synopsis (max ${MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH} UTF-16 code units) on an existing visible node using optimistic concurrency. Pass an empty string to clear it. Does not create nodes.`,
      inputSchema: {
        type: 'object',
        properties: {
          node: { type: 'string', minLength: 1 },
          expectedVersion: { type: 'integer', minimum: 1 },
          description: {
            type: 'string',
            minLength: 0,
            maxLength: MAX_KNOWLEDGE_NODE_DESCRIPTION_LENGTH,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the recordId exists via store.getKnowledge({ id }) before rescoping
2. Use IDs returned from knowledge_append / store.appendKnowledge in the same session rather than reconstructed ones
3. Check whether the record was soft-deleted (getKnowledge with includeDeleted: true) and restore or pick another record
4. Verify the Memory instance is attached to the intended knowledge storage backend

Example fix

// before
await tool.execute({ recordId: record.id, scope: 'org' });
// after
const record = await store.getKnowledge({ id: record.id, includeDeleted: true });
if (!record) throw new Error(`Record ${record.id} does not exist; cannot rescope`);
await tool.execute({ recordId: record.id, scope: 'org' });

const record = await store.getKnowledge({ id: recordId, includeDeleted: true });
if (!record) throw new Error(`Cannot rescope: record ${recordId} not found`);

function recordExists<T>(r: T | null | undefined): r is T { return r != null; }

try {
  await tool.execute({ recordId, scope });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('KnowledgeRecord not found')) {
    // refresh record list from the knowledge store
  } else throw e;
}

When it happens

Trigger: Calling knowledge_rescope with a recordId that is not present in the knowledge store, a deleted record fetched without includeDeleted, or an ID from a different Memory/storage instance.

Common situations: Curator agent reusing a recordId from a prior conversation that has since been soft-deleted; typos or truncated IDs in tool calls from the LLM; pointing the processor at a fresh database where the record was never written.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Knowledge merge requires two existing nodes.
• MastraClient.deleteThread() requires exactly one of agentId
• No response body
• @mastra/opencode: failed to initialize memory storage from $
• Could not generate title from input ${JSON.stringify(message

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