react Errors
115 error patterns
React hydration mismatch
Hydration failed because.*server rendered HTML.*didn't match
- •Ensure server and client render same content
- •Use suppressHydrationWarning for dynamic content
Text content hydration mismatch
Text content does not match server-rendered HTML
- •Don't use Date.now() or Math.random() in render
- •Use useEffect for client-only values
use client directive error in Server Component
(useClient|use client).*server component
- •Add 'use client' at top of file
- •Move useState/useEffect to client component
Client component import in Server Component
(You're importing a component that needs|can't use.*in.*Server Component)
- •Add 'use client' directive to importing file
- •Create client component wrapper
Cannot pass function to Client Component from Server
Functions cannot be passed directly to Client Components.*unless.*mark it.*"use server"
- •Mark function with 'use server' for server actions
- •Pass serializable data only
Non-serializable prop to Client Component
Only plain objects.*can be passed to Client Components from Server Components
- •Serialize data before passing (no functions, classes, Date)
- •Convert Date to ISO string
Async/await in Client Component
(async/await is not yet supported in Client Components|Cannot use async component)
- •Use useEffect + useState for data fetching
- •Move async logic to Server Component
Next.js notFound() called
Error:.*NEXT_NOT_FOUND
- •Check if data exists before rendering
- •Add not-found.tsx in route segment
Next.js redirect() in try/catch
Error:.*NEXT_REDIRECT
- •Don't wrap redirect() in try/catch
- •Move redirect outside of try block
use server on non-async function
'use server'.*only.*async functions
- •Make the function async
- •Move 'use server' to top of file for all exports
useFormState/useActionState not found
useFormState.*is not a function
- •Import from react-dom (useFormState) or react (useActionState)
- •Update to Next.js 14.1+
More hooks rendered than previous render
Rendered more hooks than during the previous render
- •Don't call hooks conditionally
- •Move hooks before early returns
Fewer hooks rendered than expected
Rendered fewer hooks than expected
- •Don't return early before hooks
- •Keep hooks at top of component
Invalid hook call outside component
Invalid hook call.*Hooks can only be called inside.*function component
- •Only call hooks in function components or custom hooks
- •Don't call hooks in regular functions/classes
Cannot update component while rendering another
Cannot update a component.*while rendering a different component
- •Move state update to useEffect
- •Don't call setState during render of parent
Too many re-renders (infinite loop)
Too many re-renders.*infinite loop
- •Don't call setState in render body
- •Use useEffect with proper deps
Maximum update depth exceeded
Maximum update depth exceeded
- •Check useEffect dependencies causing re-trigger
- •Memoize objects/arrays in dependencies
State update on unmounted component
Can't perform a React state update on.*unmounted component
- •Use cleanup function in useEffect
- •Cancel async operations on unmount
Missing unique key prop in list
Each child in a list should have a unique "key" prop
- •Add unique key prop to list items
- •Use item.id or unique identifier
React is null (duplicate React)
Cannot read properties of null.*reading 'useState'
- •Check for duplicate React in node_modules
- •Use npm dedupe
Suspense boundary needs fallback prop
Suspense.*boundary.*no fallback
- •Add fallback prop to Suspense: <Suspense fallback={<Loading/>}>
- •Provide loading UI component
Suspense hydration bailout to client render
(There was an error while hydrating this Suspense boundary|Switched to client rendering)
- •Ensure suspended content matches server HTML
- •Check for client-only logic in suspended tree
use() hook called outside component render
use\(.*\).*only.*render.*body.*React component
- •Call use() only in component render body
- •Don't call in event handlers or callbacks
Synchronous suspense without transition
A component suspended while responding to synchronous input
- •Wrap state update in startTransition
- •Use useDeferredValue for derived data
createContext in Server Component
createContext.*server component
- •Move context to client component with 'use client'
- •Use module-level variables for server state
Client hooks used in Server Component
(useRouter|usePathname|useSearchParams).*server component
- •Add 'use client' to component using router hooks
- •Access route params via page props in server components
Next.js 15 params must be awaited
'params'.*should be awaited.*before accessing
- •Await params before destructuring: const { id } = await params
- •Update to Next.js 15 async params pattern
Next.js dynamic rendering forced by cookies/headers
Route.*used.*cookies.*opt.*into dynamic rendering
- •This is expected: cookies/headers forces dynamic rendering
- •Use export const dynamic = 'force-dynamic'
headers/cookies called outside request scope
(Invariant: headers\(\)|cookies\(\)).*only.*within.*request scope
- •Only call in Server Components/Route Handlers/Middleware
- •Don't call in generateStaticParams or module scope
generateStaticParams missing for dynamic route
generateStaticParams.*dynamic route.*not found
- •Add generateStaticParams to generate all paths
- •Use dynamicParams = false to limit
Parallel route missing default.tsx
Parallel routes.*default\.tsx.*not found
- •Add default.tsx to parallel route slot
- •Export default null component for unmatched
Intercepting route convention error
'intercepting route'.*convention.*\(\.\.\)
- •Use correct convention: (.) same level, (..) one up, (...) root
- •Check folder naming matches convention
Metadata export in client component
metadata.*cannot.*exported.*client component
- •Remove 'use client' from page with metadata
- •Use generateMetadata in server components only
React Query: No QueryClient set
useQuery.*No QueryClient set
- •Wrap app with QueryClientProvider
- •Provide QueryClient instance
React Query: Missing query key
(useMutation|useQuery).*missing.*queryKey
- •Add queryKey array to options
- •Use unique key for each query
React Query QueryClient in module scope (SSR issue)
Hydration.*QueryClient.*must be created.*inside.*component
- •Create QueryClient inside component or getQueryClient()
- •Don't create at module level for SSR
Zustand store access before initialization
zustand.*Cannot access.*before initialization
- •Don't access store at module level
- •Use store inside components/hooks only
Zustand subscribe with selector issue
zustand.*subscribe.*selector
- •Use useStore(store, selector) pattern
- •Add equality function for object selectors
Jotai atom not found in Provider scope
jotai.*atom.*not found.*Provider
- •Wrap component tree with Jotai Provider
- •Use default store for providerless mode
React Hook Form register ref issue
React Hook Form.*register.*ref
- •Use {...register('name')} spread pattern
- •Don't combine ref with register
React Hook Form: control prop required
(useForm|Controller).*control.*is required
- •Pass control from useForm to Controller
- •Destructure control from useForm()
React Hook Form state update after unmount
Cannot update.*form state.*unmounted
- •Use shouldUnregister: true option
- •Reset form on unmount
Radix UI component used outside required context
Radix.*must be used within
- •Wrap with required parent component
- •Check Radix compound component structure
Radix/shadcn portal rendering issue
(Dialog|Popover|DropdownMenu).*Content.*rendered.*Portal
- •Check z-index of portal container
- •Use modal prop for Dialog
Radix Slot/asChild expects single child
Slot.*asChild.*must.*single child
- •Pass exactly one child element
- •Don't use Fragment with asChild
shadcn component not applying className
Component.*not responding to className.*shadcn
- •Use cn() utility to merge classNames
- •Check component accepts className prop
React 19 Compiler cannot compile hook
React compiler.*cannot compile.*hook
- •Add 'use no memo' directive to opt out
- •Simplify hook logic for compiler
React 19 Compiler rules violation
React compiler.*rules of react.*violated
- •Don't mutate props or state directly
- •Ensure hooks follow rules of hooks
useFormStatus not inside form
(useOptimistic|useFormStatus).*not.*descendant.*form
- •Use useFormStatus in component rendered inside <form>
- •Create child component for form status
Warning: update not wrapped in act()
(Error|Warning).*act\(\).*not wrapped
- •Wrap async state updates in act() during tests
- •Use waitFor from testing-library
NextAuth session is null/undefined
next-auth.*session.*null.*undefined
- •Wrap with SessionProvider
- •Check getServerSession() in server components
Next.js env variable undefined on client
(NEXT_PUBLIC_|env).*undefined.*client
- •Prefix with NEXT_PUBLIC_ for client access
- •Restart dev server after .env changes
Next.js path alias @ not resolving
Module not found.*Can't resolve.*@\/
- •Add paths to tsconfig.json with @/*: [./src/*]
- •Check baseUrl is set in tsconfig
Server Actions must be async functions
"use server" functions.*must be async
- •Add async keyword to function
- •Server actions must return Promise
Next.js fetch failed at build/runtime
Unhandled Runtime Error.*fetch failed
- •Check API URL is accessible during build
- •Use try/catch around fetch calls
revalidatePath/Tag only on server
(revalidatePath|revalidateTag).*only.*server
- •Call from server action or route handler
- •Don't use in client components
Dynamic usage in force-static page
Dynamic server usage.*force-static
- •Remove export const dynamic = 'force-static'
- •Move dynamic code to client component
Next.js loading.tsx not triggering
loading\.tsx.*not.*showing.*streaming
- •Ensure loading.tsx is in correct route segment
- •loading.tsx works for page-level navigation only
Next.js error.tsx must be client component
error\.tsx.*must.*'use client'
- •Add 'use client' at top of error.tsx
- •Error boundaries must be client components
Server-only exports in client component
(generateMetadata|generateStaticParams).*cannot.*'use client'
- •Remove 'use client' from page with these exports
- •Move to separate server file
Next.js middleware matcher not matching routes
middleware.*matcher.*not matching
- •Check matcher config syntax in middleware.ts
- •Use regex or array pattern for matcher
Next.js Image hostname not configured
image.*not configured.*next.config
- •Add hostname to images.remotePatterns in next.config
- •Use domains array for simple cases
useTransition isPending stuck true
(useTransition|startTransition).*isPending.*stuck
- •Ensure async operation completes or errors
- •Don't throw in transition without error boundary
useDeferredValue showing stale content
useDeferredValue.*causing.*stale
- •This is expected: shows old value during transition
- •Add visual indicator for pending state
forwardRef render function ref issue
forwardRef.*render function.*does not support.*ref
- •Use ref parameter from forwardRef callback
- •In React 19, use ref as regular prop
useImperativeHandle ref is null
useImperativeHandle.*ref.*null
- •Ensure ref is passed from parent with forwardRef
- •Check ref is not conditionally applied
flushSync called during render
flushSync.*cannot.*during.*render
- •Move flushSync to event handler or useEffect
- •Don't call during component render
Recoil: Missing RecoilRoot provider
(Recoil|atom).*RecoilRoot.*missing
- •Wrap app with <RecoilRoot>
- •Check provider is above component
Recoil/Jotai atom circular dependency
(selector|atom).*circular dependency
- •Break circular reference between atoms
- •Use atomFamily for dynamic atoms
Zustand store not properly created
Cannot read properties.*'subscribe'.*Zustand
- •Use create() from zustand correctly
- •Check store is function, not result of calling it
Zustand persist: storage is undefined (SSR)
persist.*middleware.*storage.*undefined
- •Use createJSONStorage(() => localStorage) with check
- •Skip hydration on server with skipHydration
TanStack Query: Suspense query not dehydrated
(useSuspenseQuery|prefetchQuery).*not.*dehydrated
- •Prefetch in server component and dehydrate
- •Use HydrationBoundary with dehydrated state
TanStack Query mutation onSuccess not firing
Mutation.*onSuccess.*not.*firing
- •Check mutation function doesn't throw
- •Verify onSuccess is in correct options level
Cannot find next/headers module
Cannot find module 'next/headers'
- •Only import in server components
- •Update Next.js version
useSearchParams needs Suspense boundary
(useSearchParams|useRouter).*Suspense boundary.*required
- •Wrap component using useSearchParams in Suspense
- •Add fallback for search params loading
Next.js Image requires width and height
(image|Image).*width.*height.*required
- •Add width and height props
- •Use fill prop for responsive images
Props serialization error in Server Component
Props.*cannot be.*serialized.*Server Component
- •Only pass serializable data (strings, numbers, plain objects)
- •Convert Date to string/number
window/document not defined (SSR)
(window|document|localStorage).*not defined
- •Use typeof window !== 'undefined' check
- •Access in useEffect only
ResizeObserver loop error
ResizeObserver.*loop.*completed.*undelivered notifications
- •This is usually benign and can be ignored
- •Add error boundary to catch
tRPC: No matching procedure found
(tRPC|createTRPCNext).*No.*matching.*procedure
- •Check procedure name matches router definition
- •Verify router is exported correctly
Zod validation failed in form/API
(Zod|z\.).*validation.*failed
- •Check input matches Zod schema
- •Handle validation errors with safeParse
Next.js cache not revalidating
NEXT_CACHE.*stale.*revalidate
- •Use revalidateTag() or revalidatePath()
- •Set revalidate time in fetch options
dynamic import with ssr:false still renders on server
Dynamic import.*ssr.*false.*still rendering on server
- •Ensure dynamic() wraps the component correctly
- •Use next/dynamic not React.lazy
Prop value differs between server/client render
Prop.*did not match.*server.*"".*client.*"[^"]+"
- •Use useEffect for client-only prop values
- •Add suppressHydrationWarning
Invalid DOM nesting (p in p, div in p, etc)
Warning.*validateDOMNesting
- •Fix HTML nesting: don't put block elements in inline
- •Use span instead of div inside p
Unmatched JSX closing tag
Unmatched.*closing tag
- •Match opening and closing JSX tags
- •Check for typos in component names
Server HTML missing expected element
Expected.*server HTML.*contain.*matching
- •Don't conditionally render based on client state
- •Use useEffect for conditional rendering after mount
useCallback dependency changes every render
useCallback.*dependency.*changes every render
- •Memoize dependency values
- •Move object/array creation outside render
React Hook missing dependency warning
(exhaustive-deps|React Hook.*missing dependency)
- •Add missing deps to dependency array
- •Use useCallback/useMemo for object deps
Objects not valid as React child
Objects are not valid as a React child
- •Stringify object or access specific property
- •Use JSON.stringify for debugging
Controlled to uncontrolled component switch
A component is changing.*controlled.*to.*uncontrolled
- •Initialize state with empty string not undefined
- •Always provide value prop once set
React deprecated API usage
(findDOMNode|legacy context|UNSAFE_).*deprecated
- •Use refs instead of findDOMNode
- •Use new Context API
Next.js route group layout conflict
route.*group.*\(.*\).*layout.*conflict
- •Ensure route groups don't share layout paths
- •Move shared layout to parent
Next.js route special files not recognized
(generateSitemaps|generateImageMetadata).*not recognized
- •Check file is in correct directory
- •Verify Next.js version supports the API
Next.js unstable_cache revalidation issues
unstable_cache.*revalidate.*not working
- •Tag cache entries for revalidation
- •Use revalidateTag after mutation
server-only package imported in client
server-only.*imported.*client.*bundle
- •Don't import server-only modules in 'use client' files
- •Split server/client code into separate files
Turbopack module resolution failure
(TURBOPACK|turbo).*Module not found
- •Check turbo.json configuration
- •Some packages not yet compatible with Turbopack
Radix UI Portal mount point is null
(Slot|Portal).*mount.*node.*null
- •Ensure portal container exists in DOM
- •Use container prop to specify mount point
cmdk/Command component not rendering items
(cmdk|Command).*not rendering.*items
- •Check Command.Item key prop
- •Verify filter function returns results
Sonner/toast not showing notifications
(Sonner|toast).*not showing.*Provider
- •Add <Toaster /> component to layout
- •Check toast import from correct package
Invalid hook call
Invalid hook call\. Hooks can only be called inside of the body of a function component
- •Ensure hooks are only called at the top level of a function component, not inside loops, conditions, or nested functions
- •Check for multiple copies of React in your bundle: run `npm ls react` and deduplicate
Too many re-renders (infinite loop)
Too many re-renders\. React limits the number of renders to prevent an infinite loop
- •Avoid calling setState directly in the render body — wrap in useEffect or event handler
- •Ensure onClick passes a function reference, not a function call: `onClick={() => fn()}` not `onClick={fn()}`
Missing key prop in list
Each child in a list should have a unique "key" prop
- •Add a unique `key` prop to each element returned in a .map() call
- •Use a stable unique identifier (id) instead of array index as key
Cannot update state on unmounted component
Can't perform a React state update on an unmounted component
- •Return a cleanup function from useEffect to cancel async operations (e.g., AbortController)
- •Use a mounted ref flag: `const mounted = useRef(true)` and check before setState
useEffect missing dependency (exhaustive-deps)
React Hook useEffect has a missing dependency
- •Add the missing variable to the dependency array
- •Wrap the dependency in useCallback or useMemo to stabilize its reference
Hook called outside component or custom hook
React Hook .+ cannot be called at the top level
- •Move the hook call inside a function component or a custom hook (function starting with 'use')
- •Ensure the file exports a component or custom hook, not a plain function
Adjacent JSX elements not wrapped
Adjacent JSX elements must be wrapped in an enclosing tag
- •Wrap sibling elements in a parent `<div>` or `<section>`
- •Use a React Fragment: `<>...</>` or `<React.Fragment>...</React.Fragment>`
Uncontrolled to controlled input switch
A component is changing an? uncontrolled input to be controlled
- •Initialize state with an empty string instead of undefined: `useState('')` not `useState()`
- •Ensure the value prop is never undefined — use `value={val || ''}` as fallback
Controlled to uncontrolled input switch
A component is changing a controlled input to be uncontrolled
- •Ensure the value prop never becomes undefined — provide a fallback empty string
- •Check that state isn't being set to undefined anywhere in your handlers
React hydration mismatch
Hydration failed because the initial UI does not match what was rendered on the server
- •Ensure server and client render identical HTML — avoid Date.now(), Math.random() in initial render
- •Use useEffect for browser-only content (window, localStorage) so it only runs on client
Complex expression in useEffect deps
React Hook .+ has a complex expression in the dependency array
- •Extract the complex expression into a variable before the hook
- •Use useMemo to compute the derived value and pass that to the dependency array
Object rendered as React child
Objects are not valid as a React child
- •Convert the object to a string: use JSON.stringify(obj) or access a specific property
- •If rendering a list, map the array to JSX elements instead of rendering the array directly
Maximum update depth exceeded
Maximum update depth exceeded
- •Check for setState calls inside useEffect that trigger the same effect (circular update)
- •Ensure event handlers don't unconditionally call setState that re-triggers rendering
Cannot read properties of undefined/null
Cannot read propert(y|ies) of (undefined|null)
- •Add optional chaining: `obj?.property` instead of `obj.property`
- •Add a null check or default value before accessing the property
Hooks rendered conditionally (different count)
Rendered fewer hooks than expected|Rendered more hooks than expected
- •Never place hooks inside if/else blocks, loops, or after early returns
- •Move conditional logic inside the hook, not around it