mastra-ai/mastra · error · KnowledgeNotFoundError

record

Error message

record

What it means

rescopeKnowledge() throws KnowledgeNotFoundError('record', id) when the given record ID does not exist, before canonicalizing the new scope. It then verifies the requested scope fits within the record's maxScope ceiling. Note this error surfaces the record ID through KnowledgeNotFoundError even though the raw message reads 'record'.

Source

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

    this.#recordActivity('record-deleted', 'record', id, record.scope, record.sourceThreadId);
    this.#enqueue('record', id, 'delete', updated.deletedAt.toISOString(), record.scope);
    return cloneRecord(updated);
  }

  async restoreKnowledge({ id }: { id: string }): Promise<KnowledgeRecord> {
    const record = this.#db.knowledgeRecords.get(id);
    if (!record) throw new KnowledgeNotFoundError('record', id);
    if (!record.deletedAt) return cloneRecord(record);
    const updated = { ...record, deletedAt: undefined, deletedBy: undefined };
    this.#db.knowledgeRecords.set(id, updated);
    this.#recordActivity('record-restored', 'record', id, record.scope, record.sourceThreadId);
    this.#enqueue('record', id, 'upsert', createKnowledgeUlid(), record.scope);
    return cloneRecord(updated);
  }

  async rescopeKnowledge({ id, scope }: { id: string; scope: KnowledgeScope }): Promise<KnowledgeRecord> {
    const record = this.#db.knowledgeRecords.get(id);
    if (!record) throw new KnowledgeNotFoundError('record', id);
    const canonical = canonicalizeKnowledgeScope(scope);
    assertKnowledgeScopeWithinCeiling(canonical, record.maxScope);
    const updated = { ...record, scope: canonical };
    this.#db.knowledgeRecords.set(id, updated);
    this.#recordActivity('record-rescoped', 'record', id, canonical, record.sourceThreadId);
    if (knowledgeScopeKey(record.scope) !== knowledgeScopeKey(canonical)) {
      this.#enqueue('record', id, 'delete', createKnowledgeUlid(), record.scope);
    }
    if (!record.deletedAt) {
      this.#enqueue('record', id, 'upsert', createKnowledgeUlid(), canonical);
    }
    return cloneRecord(updated);
  }

  async raiseKnowledgeCeiling({
    id,
    maxScope,
  }: {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Fetch fresh record IDs (listKnowledge) immediately before rescoping in bulk jobs.
2. Wrap rescopes in error handling that logs and skips missing records rather than aborting the batch.
3. Verify the storage instance/tenant context matches where the record was created.
4. Persist records durably (a storage adapter) if IDs must survive restarts.

Example fix

// before
for (const id of cachedIds) await storage.rescopeKnowledge({ id, scope });
// after
for (const id of cachedIds) {
  try { await storage.rescopeKnowledge({ id, scope }); }
  catch (e) { if (!(e instanceof KnowledgeNotFoundError)) throw e; }
}

const records = await storage.listKnowledge({});
const target = records.records.find(r => r.id === id);
if (!target) throw new SkipRescope(`record ${id} not found`);
if (!isKnowledgeScopeWithinCeiling(newScope, target.maxScope)) throw new SkipRescope('scope exceeds ceiling');

try {
  await storage.rescopeKnowledge({ id, scope });
} catch (e) {
  if (e instanceof KnowledgeNotFoundError) { skipped.push(id); return; }
  throw e;
}

When it happens

Trigger: Calling rescopeKnowledge({ id, scope }) with an ID that was never created, an ID from another instance/environment, or an ID captured before the store was reinitialized; rescoping records loaded from a stale list snapshot.

Common situations: Bulk rescope jobs built from cached IDs across process restarts; multi-tenant code pointing at the wrong store; ID copy/paste between dev and prod data.

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

• Invalid knowledge scope entry: ${entry}
• Knowledge scope contains multiple ${level} entries
• Knowledge scope cannot be empty
• Thread knowledge scope requires resource and org ancestors
• Resource knowledge scope requires an org ancestor

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