Build errors

The kit uses Next.js 16 with cacheComponents: true. It's stricter than older Next.js, and AI agents trained on older versions often write code that breaks these rules. Many of these errors only appear in npm run build, not in npm run dev, so run the build after changing pages.

Uncached data accessed outside <Suspense>Copy Anchor Link

Error: Route "/dashboard/reports": Next.js encountered uncached or runtime data during prerendering.

The dev overlay calls this a blocking route.

Why: a page or layout reads the session, headers(), cookies(), searchParams or the database at its top level, so Next can't render any of the page ahead of time.

Fix: move that work into a child component and wrap it in <Suspense>:

// Before: awaits at the top of the page
export default async function Page() {
  const user = await requireUser();
  return <Reports user={user} />;
}

// After
export default function Page() {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <ReportsForUser />
    </Suspense>
  );
}

async function ReportsForUser() {
  const user = await requireUser();
  return <Reports user={user} />;
}

new Date() or Math.random() during prerenderingCopy Anchor Link

Why: a server component uses the current time or a random value outside <Suspense>. Next can't know whether the value should be fixed at build time or fresh on every request.

Fix: pick one:

• Fresh on every request: put the component inside <Suspense> and call await connection() (from next/server) before new Date().
• Fixed until the cache refreshes: add "use cache" at the top of the function.
• Shown in the browser only: move it to a client component.

Data from files without "use cache"Copy Anchor Link

Why: a page reads files or another non-request source (for example, a list of MDX files) while rendering, without caching.

Fix: add "use cache" to the function that reads the data. See src/lib/blog.ts for an example.

Route segment config "dynamicParams" is not compatible with nextConfig.cacheComponentsCopy Anchor Link

Why: a page exports dynamicParams, which isn't allowed with cacheComponents.

Fix: remove the export. To 404 unknown slugs, check the param in the page and call notFound().

params or searchParams used without awaitCopy Anchor Link

Property 'slug' does not exist on type 'Promise<{ slug: string; }>'.

Why: in Next.js 16, params, searchParams, cookies() and headers() are promises.

Fix: const { slug } = await props.params; (inside <Suspense> for searchParams).

middleware.ts is ignoredCopy Anchor Link

Why: Next.js 16 renamed middleware to proxy. The kit's is src/proxy.ts, exporting a proxy function.

Fix: put your logic in src/proxy.ts, not a new middleware.ts.

Functions exported from a client component can't be called on the serverCopy Anchor Link

Error: Attempted to call formatThing() from the server but formatThing is on the client.

Why: a file with "use client" exports a helper that a server component imports.

Fix: move the helper to a plain module without "use client" (for example in src/lib/), and import it from both.

You're importing a component that needs "server-only"Copy Anchor Link

'server-only' cannot be imported from a Client Component module.

Why: a client component imports server code (@/lib/auth, @/db, @/lib/billing…), which would leak secrets to the browser.

Fix: keep that code in server components or server actions, and pass only the data the client needs as props.

asChild doesn't exist on ButtonCopy Anchor Link

Property 'asChild' does not exist on type 'IntrinsicAttributes & ButtonProps'.

Why: the UI components are shadcn/ui on Base UI, which uses a render prop instead of Radix's asChild.

Fix:

<Button nativeButton={false} render={<Link href="/pricing" />}>
  See pricing
</Button>

Type errors in .next/types after deleting a pageCopy Anchor Link

Why: Next's generated route types still mention the deleted route.

Fix: rm -rf .next and run npm run typecheck again (it regenerates them).

Lint errorsCopy Anchor Link

npm run lint uses ESLint with Next's rules. Read the rule name at the end of each message; most messages say how to fix them. Common ones:

Tests failCopy Anchor Link

Run npm test and read the first failing test. The kit's tests cover webhook signatures, checkout, the .env.local writer and repository access. If a test fails after you changed billing code, the change probably broke one of the webhook rules.