mastra-ai/mastra · error · HTTPException

Thread not found

Error message

Thread not found

What it means

The GET thread handler in the Mastra server resolves memory via the agent's memory instance and calls getThreadById. When no thread row exists for the requested threadId, it throws HTTPException(404, 'Thread not found'). This is a deliberate 404 so clients can distinguish 'unknown thread' from storage/authorization failures.

Source

Thrown at packages/server/src/server/handlers/memory.ts:1032

            };
          }
          const thread = toLocalThread(result.thread);
          await enforceThreadAccess({
            mastra,
            requestContext,
            threadId: effectiveThreadId!,
            thread,
            effectiveResourceId,
          });
          return thread;
        }
      }

      const memory = await getMemoryFromContext({ mastra, agentId, requestContext, allowMissingAgent: true });
      if (memory) {
        const thread = await memory.getThreadById({ threadId: effectiveThreadId! });
        if (!thread) {
          throw new HTTPException(404, { message: 'Thread not found' });
        }
        await enforceThreadAccess({
          mastra,
          requestContext,
          threadId: effectiveThreadId!,
          thread,
          effectiveResourceId,
        });
        return thread;
      }

      // Fallback to storage (covers stored agents whose memory can't be resolved)
      const storage = getStorageFromContext({ mastra });
      if (storage) {
        const memoryStore = await storage.getStore('memory');
        if (memoryStore) {
          const thread = await memoryStore.getThreadById({ threadId: effectiveThreadId! });
          if (!thread) {

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Verify the threadId exists by listing threads (GET /api/memory/threads?resourceid=...) and using a returned id.
  2. Check that the server's memory storage configuration (connection string/env) points to the same database the thread was created in.
  3. If the thread was deleted intentionally, create a new thread (e.g. via a new agent run) instead of reusing the stale id.
  4. Confirm the resourceid association if your storage scopes threads per resource.

Example fix

// before
const res = await fetch(`/api/memory/threads/${staleThreadId}`);
// after
const threads = await fetch(`/api/memory/threads?resourceid=${resourceId}`).then(r => r.json());
const id = threads.find(t => t.id === desiredTitle)?.id ?? threads[0]?.id;
const res = await fetch(`/api/memory/threads/${id}`);
Defensive patterns

Strategy: try-catch

Validate before calling

const threads = await fetch(`/api/memory/threads?resourceid=${resourceId}`).then(r => r.json());
if (!threads.some(t => t.id === threadId)) throw new Error(`Thread ${threadId} does not exist for resource ${resourceId}`);

Type guard

function isThread(t: unknown): t is { id: string } {
  return !!t && typeof t === 'object' && typeof (t as any).id === 'string';
}

Try / catch

try {
  const thread = await getThread(threadId);
} catch (e) {
  if (isHttpException(e, 404)) {
    thread = await createNewThread(resourceId); // recover by starting fresh
  } else throw e;
}

Prevention

When it happens

Trigger: GET /api/memory/threads/:threadId (get thread by id) where memory is resolvable from the agent/context but memory.getThreadById({ threadId }) returns undefined — i.e. the threadId does not exist in the configured memory storage.

Common situations: Client uses a thread id from a different environment/database; thread was deleted by memory TTL/cleanup or a prior delete call; typo'd or stale thread id cached in the frontend; point-in-time restore of the storage DB removed recent threads; pointing at a different storage backend via env (e.g. different Postgres/Upstash database).

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

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