mastra-ai/mastra · error · HTTPException

Server cache not found

Error message

Server cache not found

What it means

A 500 thrown when `mastra.getServerCache()` returns undefined on the observe-stream route. The server's chunk cache is not configured, so cached stream chunks cannot be served alongside the live stream.

Source

Thrown at packages/server/src/server/handlers/workflows.ts:795

      const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });

      if (!workflow) {
        throw new HTTPException(404, { message: 'Workflow not found' });
      }

      const run = await workflow.getWorkflowRunById(runId);

      if (!run) {
        throw new HTTPException(404, { message: 'Workflow run not found' });
      }

      await validateRunOwnership(run, effectiveResourceId);

      const _run = await workflow.createRun({ runId, resourceId: run.resourceId });
      const serverCache = mastra.getServerCache();
      if (!serverCache) {
        throw new HTTPException(500, { message: 'Server cache not found' });
      }

      // Get cached chunks from the specified index (or 0 if not specified)
      const startIndex = offset ?? 0;
      const cachedRunChunks = (await serverCache.listFromTo(runId, startIndex)) as ChunkType[];
      const liveStream = _run.observeStream();

      return createReplayStream<ChunkType>({
        history: cachedRunChunks,
        liveSource: liveStream,
      });
    } catch (error) {
      return handleError(error, 'Error observing workflow stream');
    }
  },
});

export const RESUME_ASYNC_WORKFLOW_ROUTE = createRoute({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure the server cache in your Mastra server setup (enable the built-in cache store)
2. Upgrade @mastra/core and @mastra/deployer/server packages to matching versions so the cache is wired by default
3. If you don't need cached chunks, avoid the observe-with-offset route or upgrade to a version that handles a missing cache gracefully

Example fix

// before
new Mastra({ agents, workflows }) // custom server without cache
// after
new Mastra({ agents, workflows, server: { experimental: { streamInterruption: true } }, ... }) // ensure server cache configured per current docs

const cache = (mastra as any)?.getServerCache?.();
if (!cache) console.warn('Server cache not configured — observe-stream with offsets will fail (500)');

function hasServerCache(m: unknown): m is { getServerCache(): NonNullable<unknown> } {
  const c = (m as any)?.getServerCache?.();
  return !!c;
}

try {
  await client.getWorkflow(workflowId).observeStream({ runId, offset });
} catch (e: any) {
  if (e?.status === 500 && /Server cache not found/.test(e?.message ?? '')) {
    console.error('Server cache missing: enable stream-interruption/server-cache in Mastra server config');
    // fall back to polling run status instead of observing chunks
  } else throw e;
}

When it happens

Trigger: Observing a workflow stream on a Mastra instance whose server configuration lacks the server cache (e.g. cache store not configured for resume/observe of mid-stream runs).

Common situations: Custom/self-hosted Mastra server without the server cache wiring; version mismatch where handler expects getServerCache but the instance doesn't set it; disabling cache in config while still using observe-stream with offsets.

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Storage is not configured
• Storage is not configured
• Mastra instance is required for conversations

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