mastra-ai/mastra · error · KnowledgeNotFoundError

Knowledge node not found: ${id}

Error message

Knowledge node not found: ${id}

What it means

updateNode was called with an id that does not exist in the knowledgeNodes map; the store throws KnowledgeNotFoundError('node', id). The node was never created, was deleted, or the id is wrong (or belongs to a different store instance).

Source

Thrown at packages/core/src/storage/domains/knowledge/inmemory.ts:206

      .filter(
        node =>
          !cursor ||
          node.updatedAt < cursor.updatedAt ||
          (node.updatedAt.getTime() === cursor.updatedAt.getTime() &&
            (node.name > cursor.name || (node.name === cursor.name && node.id > cursor.id))),
      )
      .slice(0, input.limit ?? 100)
      .map(cloneNode);
  }

  async updateNode(input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode> {
    return this.#runAtomicMutation(() => this.#updateNode(input));
  }

  #updateNode(input: UpdateKnowledgeNodeInput): KnowledgeNode {
    assertKnowledgeDescriptionWithinBound(input.description);
    const existing = this.#db.knowledgeNodes.get(input.id);
    if (!existing) throw new KnowledgeNotFoundError('node', input.id);
    if (existing.version !== input.version) throw new KnowledgeConflictError(input.id);
    if (existing.mergedInto) throw new Error(`Cannot update merged knowledge node: ${input.id}`);

    const scope = canonicalizeKnowledgeScope(input.scope ?? existing.scope);
    const name = (input.name ?? existing.name).trim();
    const oldKey = recordKey(existing.name, existing.scope);
    const newKey = recordKey(name, scope);
    const collision = this.#db.knowledgeNodeKeys.get(newKey);
    if (collision && collision !== input.id) throw new Error(`Knowledge node already exists in scope: ${name}`);

    const updated: KnowledgeNode = {
      ...existing,
      name,
      kind: input.kind ?? existing.kind,
      content: input.content ?? existing.content,
      description: input.description ?? existing.description,
      scope,
      version: existing.version + 1,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the id by listing/fetching nodes before updating (getNode with the same id)
2. Create the node if it does not exist (upsert pattern: try update, on KnowledgeNotFoundError call createNode)
3. Fix persistence: switch to a durable storage domain if node ids must survive process restarts

Example fix

// before
await store.updateNode({ id, version: 1, description: 'new' });
// after
try {
  await store.updateNode({ id, version: 1, description: 'new' });
} catch (e) {
  if (e instanceof KnowledgeNotFoundError) await store.createNode({ name, scope, description: 'new' });
  else throw e;
}

const existing = await store.getNode({ id, resolutionScope: scope }).catch(() => null);
if (!existing) throw new Error(`cannot update: node ${id} does not exist`);

function isKnowledgeNode(v: unknown): v is KnowledgeNode {
  return !!v && typeof v === 'object' && 'id' in v && 'version' in v;
}

try {
  await store.updateNode({ id, version, ...patch });
} catch (e) {
  if (e instanceof KnowledgeNotFoundError) {
    await store.createNode({ name, scope, ...patch });
  } else throw e;
}

When it happens

Trigger: Calling updateNode({ id }) where #db.knowledgeNodes.has(id) is false: typo'd id, node deleted in a prior call, or updating against a different/refreshed in-memory store instance that lost the node.

Common situations: Holding a node id from a previous process run while using an in-memory store (data is not persistent); deleting the node earlier in the same workflow; id copied from the wrong environment.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Merged knowledge node is not visible from scope: ${input.nam
• Knowledge node already exists: ${node.id}
• Cannot update merged knowledge node: ${input.id}
• Pin not found: ${recordId}
• Model "${modelId}" is not available. Available models: ${ids

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