fix(start-plugin-core): prerender retryCount never retries, failOnError never fails the build

.changeset/prerender-retry-fail-on-error.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-plugin-core': patch
+---
+
+Fix `prerender.retryCount` never actually retrying a failed page (the path was already marked "seen" on the first attempt, so the retry was silently dropped), and fix `prerender.failOnError` not failing the build once retries were exhausted (the queued task's rejection was never awaited, so it became an unhandled promise rejection instead of stopping the build).

packages/start-plugin-core/src/prerender.ts

@@ -86,6 +86,10 @@ export async function prerender({
     const seen = new Set<string>()
     const prerendered = new Set<string>()
     const retriesByPath = new Map<string, number>()
+    // Collects rejections from queue.add() tasks (e.g. failOnError) so they
+    // can be rethrown after the queue settles, instead of becoming unhandled
+    // promise rejections that let the build exit 0 with pages missing.
+    const taskErrors: Array<unknown> = []
     const concurrency = startConfig.prerender?.concurrency ?? os.cpus().length
     logger.info(`Concurrency: ${concurrency}`)
     const queue = new Queue({ concurrency })
@@ -106,6 +110,13 @@ export async function prerender({
 
     await queue.start()
 
+    if (taskErrors.length) {
+      throw new AggregateError(
+        taskErrors,
+        `Failed to prerender ${taskErrors.length} page(s)`,
+      )
+    }
+
     return Array.from(prerendered)
 
     function addCrawlPageTask(page: Page) {
@@ -131,7 +142,7 @@ export async function prerender({
         ...page.prerender,
       }
 
-      queue.add(async () => {
+      const task = queue.add(async () => {
         logger.info(`Crawling: ${page.path}`)
         const retries = retriesByPath.get(page.path) || 0
 
@@ -219,12 +230,26 @@ export async function prerender({
             )
             await new Promise((resolve) => setTimeout(resolve, retryDelay))
             retriesByPath.set(page.path, retries + 1)
+            // `seen` guards addCrawlPageTask against re-queuing a page that's
+            // already in flight/queued, but that also blocked the retry
+            // itself (the path was marked seen on the first attempt). Clear
+            // it so the retry actually gets queued.
+            seen.delete(page.path)
             addCrawlPageTask(page)
           } else if (prerenderOptions.failOnError ?? true) {
             throw error
           }
         }
       })
+
+      // `queue.add()` returns a promise that settles with the task, but
+      // nothing awaited it here, so a rejection (failOnError) became an
+      // unhandled promise rejection - the queue's own `isSettled()` doesn't
+      // care whether tasks succeeded, so `await queue.start()` below resolved
+      // and the build could exit 0 with pages missing. Collect it instead.
+      task.catch((error: unknown) => {
+        taskErrors.push(error)
+      })
     }
   }
 

packages/start-plugin-core/tests/prerender-retry.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from 'vitest'
+import { prerender } from '../src/prerender'
+import type { TanStackStartOutputConfig } from '../src/schema'
+import type * as Utils from '../src/utils'
+import type * as Fs from 'node:fs'
+
+vi.mock('../src/utils', async () => {
+  const actual = await vi.importActual<typeof Utils>('../src/utils')
+  return {
+    ...actual,
+    createLogger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
+  }
+})
+
+// Mock fs to prevent actual file system operations
+vi.mock('node:fs', async () => {
+  const actual = await vi.importActual<typeof Fs>('node:fs')
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      mkdir: vi.fn().mockResolvedValue(undefined),
+      writeFile: vi.fn().mockResolvedValue(undefined),
+    },
+  }
+})
+
+function makeStartConfig(
+  pagePath: string,
+  prerenderOverrides: Record<string, unknown> = {},
+) {
+  return {
+    prerender: {
+      enabled: true,
+      autoStaticPathsDiscovery: false,
+      concurrency: 1,
+      // keep retries fast in tests
+      retryDelay: 1,
+      ...prerenderOverrides,
+    },
+    pages: [{ path: pagePath }],
+    router: { basepath: '' },
+    spa: {
+      enabled: false,
+      prerender: {
+        outputPath: '/_shell',
+        crawlLinks: false,
+        retryCount: 0,
+        enabled: true,
+      },
+    },
+    // Only a subset of TanStackStartOutputConfig is needed to exercise
+    // prerender(); building the full parsed schema shape isn't worth it here.
+  } as unknown as TanStackStartOutputConfig
+}
+
+const handler = {
+  getClientOutputDirectory: () => '/client',
+}
+
+describe('prerender retries', () => {
+  it('retries a page that fails and succeeds before exhausting retryCount', async () => {
+    let calls = 0
+    const request = vi.fn(() => {
+      calls++
+      if (calls <= 2) {
+        return new Response('nope', { status: 500 })
+      }
+      return new Response('<html></html>', {
+        status: 200,
+        headers: { 'content-type': 'text/html' },
+      })
+    })
+
+    const startConfig = makeStartConfig('/about', { retryCount: 2 })
+
+    await expect(
+      prerender({ startConfig, handler: { ...handler, request } }),
+    ).resolves.not.toThrow()
+
+    // 1 initial attempt + 2 retries, third attempt succeeds
+    expect(request).toHaveBeenCalledTimes(3)
+  })
+
+  it('rethrows once retries are exhausted and failOnError is true', async () => {
+    const request = vi.fn(() => new Response('nope', { status: 500 }))
+
+    const startConfig = makeStartConfig('/about', {
+      retryCount: 1,
+      failOnError: true,
+    })
+
+    await expect(
+      prerender({ startConfig, handler: { ...handler, request } }),
+    ).rejects.toThrow()
+
+    // 1 initial attempt + 1 retry, both fail
+    expect(request).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not throw when retries are exhausted and failOnError is false', async () => {
+    const request = vi.fn(() => new Response('nope', { status: 500 }))
+
+    const startConfig = makeStartConfig('/about', {
+      retryCount: 1,
+      failOnError: false,
+    })
+
+    await expect(
+      prerender({ startConfig, handler: { ...handler, request } }),
+    ).resolves.not.toThrow()
+
+    expect(request).toHaveBeenCalledTimes(2)
+  })
+})