vercel/ai · error · Error

Timed out waiting for snapshot of template "${name}" to publ

Error message

Timed out waiting for snapshot of template "${name}" to publish.

What it means

pollForTemplateSnapshot waits for a template's snapshot to publish after creating a session from a template. If the snapshot does not become available (currentSnapshotId stays undefined) before the polling loop exhausts its attempts, it throws this plain Error. This indicates the Vercel Sandbox platform did not finish publishing the template snapshot in time.

Source

Thrown at packages/sandbox-vercel/src/vercel-sandbox.ts:452

  abortSignal: AbortSignal | undefined;
}): Promise<string> {
  const deadline = Date.now() + SNAPSHOT_POLL_TIMEOUT_MS;
  while (Date.now() < deadline) {
    abortSignal?.throwIfAborted();
    const refreshed = await Sandbox.get({
      ...lookupParams,
      name,
      resume: false,
      ...(abortSignal ? { signal: abortSignal } : {}),
    });
    if (refreshed.currentSnapshotId) {
      return refreshed.currentSnapshotId;
    }
    await new Promise<void>(resolve =>
      setTimeout(resolve, SNAPSHOT_POLL_INTERVAL_MS),
    );
  }
  throw new Error(
    `Timed out waiting for snapshot of template "${name}" to publish.`,
  );
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Retry createSession — the template snapshot may publish eventually.
Check the template builds/publishes correctly in the Vercel dashboard.
Use a stable, pre-published template instead of one that must snapshot on demand.
Increase headroom: pin the template so its snapshot is already warm before your call.

Defensive patterns

Strategy: retry

Validate before calling

null

Type guard

null

Try / catch

try {
  await createSession({ template });
} catch (error) {
  if (error.message.includes('Timed out waiting for snapshot')) {
    // retry with backoff or fall back to a pre-published template
  } else throw error;
}

Prevention

Pre-warm/publish templates before production use.
Retry createSession with exponential backoff.
Monitor Vercel platform status during incidents.
Prefer stable, already-snapshotted templates.

When it happens

Trigger: Calling createSession with a template whose snapshot build is slow, queued, or failed; the loop polls every SNAPSHOT_POLL_INTERVAL_MS until the overall timeout elapses without a snapshot ID appearing.

Common situations: Cold/rarely-used templates that take long to build; Vercel platform delays or outages; network latency; using a custom template whose image build fails silently.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ded60bf4eb970f32. Report an issue: GitHub.