What causes "${this.name}: entity with id ${id} not found" in mastra-ai/mastra?

Verify the entity exists with get() before calling update, or catch the error and create the entity instead.

${this.name}: entity with id ${id} not found

Error message

${this.name}: entity with id ${id} not found

What it means

updateEntity hydrates state and looks up the entity by id; if it is absent the update is rejected with this error rather than silently no-oping. Only the 'id' key and whitelisted fields are later merged, so the store requires an existing record as the merge base.

Source

Thrown at packages/core/src/storage/filesystem-versioned.ts:502

  async getById(id: string): Promise<TEntity | null> {
    this.hydrate();
    return this.entities.has(id) ? structuredClone(this.entities.get(id)!) : null;
  }

  async createEntity(id: string, entity: TEntity): Promise<TEntity> {
    this.hydrate();
    if (this.entities.has(id)) {
      throw new Error(`${this.name}: entity with id ${id} already exists`);
    }
    this.entities.set(id, structuredClone(entity));
    return structuredClone(entity);
  }

  async updateEntity(id: string, updates: Record<string, unknown>): Promise<TEntity> {
    this.hydrate();
    const existing = this.entities.get(id);
    if (!existing) {
      throw new Error(`${this.name}: entity with id ${id} not found`);
    }

    const updated = { ...existing } as Record<string, unknown>;

    for (const [key, value] of Object.entries(updates)) {
      if (key === 'id') continue;
      if (value === undefined) continue;

      if (key === 'metadata' && typeof value === 'object' && value !== null) {
        updated['metadata'] = {
          ...((updated['metadata'] as Record<string, unknown> | undefined) ?? {}),
          ...(value as Record<string, unknown>),
        };
      } else {
        updated[key] = value;
      }
    }
    updated['updatedAt'] = new Date();

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the entity exists with get() before calling update, or catch the error and create the entity instead.
Refresh the id from a fresh list/get call to rule out a stale or deleted record.
Fix the id (check casing/typos) against the storage directory contents.

Example fix

// before
await store.update('agents', id, { name: 'new-name' });
// after
const existing = await store.get('agents', id);
if (!existing) throw new Error(`Agent ${id} no longer exists`);
await store.update('agents', id, { name: 'new-name' });

Defensive patterns

Strategy: try-catch

Validate before calling

const existing = await store.get('entities', id);
if (!existing) throw new Error(`Cannot update: entity ${id} not found`);

Try / catch

try {
  await store.update('entities', id, updates);
} catch (e) {
  if (String(e.message).includes('not found')) {
    // handle deleted/stale record: recreate or surface to user
  } else throw e;
}

Prevention

Re-fetch the entity right before updating to avoid stale-id updates.
Handle concurrent deletes in UI code (refresh lists after mutations).
Validate id casing/format before issuing the update.

When it happens

Trigger: Calling store.update('entities', id, updates) (delegating to updateEntity) where no entity with that id exists; updating an id that was deleted on disk before hydration; a typo'd or stale id captured from an older list result.

Common situations: Editing a record that another user/process deleted; frontend holding a stale id after a delete; test fixtures referencing ids that were never seeded.

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

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