Next.js 14: Debugging the Server-Client Boundary

Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".
  at stringify (...next/dist/server/app-render/app-render.js:...)

Error: Only plain objects, and a few built-ins, can be passed to Client Components from Server Components.
Classes or null prototypes are not supported.

// ❌ Date object is not serializable
async function Page() {
  const post = await db.post.findFirst()
  return <PostCard publishedAt={post.createdAt} /> // Date → crash
}

// ✅ Serialize to ISO string before passing
async function Page() {
  const post = await db.post.findFirst()
  return <PostCard publishedAt={post.createdAt.toISOString()} />
}

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Warning: Expected server HTML to contain a matching <div> in <div>.

See more info here: https://nextjs.org/docs/messages/react-hydration-error

'use client'
import { useEffect, useState } from 'react'

// ❌ Crashes: window is undefined on the server
export function ViewCount() {
  const stored = localStorage.getItem('views') ?? '0'
  return <span>{stored} views</span>
}

// ✅ Mount-safe: reads localStorage only after hydration
export function ViewCount() {
  const [views, setViews] = useState<string | null>(null)

  useEffect(() => {
    setViews(localStorage.getItem('views') ?? '0')
  }, [])

  if (views === null) return <span>- views</span>
  return <span>{views} views</span>
}

0:["$","div",null,{"className":"prose"},["$","h1",null,{},"Hello"]]
1:{"id":"cjld2cyuq0000t3rmniod1fga","title":"Hello World","createdAt":"2026-01-01T00:00:00.000Z"}

Module build failed: You're importing a component that needs "server-only"
but none of its parents are marked with "use server", nor are they a Server Component.

npm install server-only

// lib/db.ts
import 'server-only'     // ← throws at build time if imported in a Client Component
import { PrismaClient } from '@prisma/client'

const db = new PrismaClient()
export { db }

// app/actions.ts
'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  if (!title) throw new Error('Title is required')
  await db.post.create({ data: { title } })
}

'use server'
import { z } from 'zod'

const schema = z.object({ title: z.string().min(1).max(200) })

export async function createPost(formData: FormData) {
  const parsed = schema.safeParse({ title: formData.get('title') })
  if (!parsed.success) throw new Error('Invalid input')
  await db.post.create({ data: parsed.data })
}

'use client'
import { useActionState } from 'react'
import { createPost } from './actions'

export function PostForm() {
  const [error, action, isPending] = useActionState(
    async (_prev: string | null, formData: FormData) => {
      try {
        await createPost(formData)
        return null
      } catch (e) {
        return (e as Error).message
      }
    },
    null
  )

  return (
    <form action={action}>
      <input name="title" />
      {error && <p className="text-red-500">{error}</p>}
      <button disabled={isPending}>
        {isPending ? 'Saving…' : 'Create Post'}
      </button>
    </form>
  )
}

// app/api/user/route.ts
import { experimental_taintObjectReference } from 'react'

async function getUser(id: string) {
  const user = await db.user.findUnique({ where: { id } })
  // Mark the whole object as tainted - passing it as a prop will throw
  experimental_taintObjectReference(
    'Do not pass user objects to Client Components. Serialize only the fields you need.',
    user
  )
  return user
}

/** @type {import('next').NextConfig} */
module.exports = {
  experimental: {
    taint: true,
  },
}

// ❌ Forces everything into client bundle
'use client'
export default function BlogPage({ posts }) {
  const [filter, setFilter] = useState('')
  return (
    <div>
      <input onChange={(e) => setFilter(e.target.value)} />
      {posts.map(p => <PostCard key={p.id} post={p} />)}
    </div>
  )
}

// ✅ Only the filter widget is a Client Component
// BlogPage and PostCard remain Server Components
'use client'
export function FilterInput({ onFilter }: { onFilter: (q: string) => void }) {
  return <input onChange={(e) => onFilter(e.target.value)} />
}

// This pattern works - children are still Server Components
export default function Layout({ children }: { children: React.ReactNode }) {
  return <ClientShell>{children}</ClientShell>
}