react Errors

115 error patterns

react3 fixes

React hydration mismatch

Hydration failed because.*server rendered HTML.*didn't match

  • Ensure server and client render same content
  • Use suppressHydrationWarning for dynamic content
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

Next.js notFound() called

Error:.*NEXT_NOT_FOUND

  • Check if data exists before rendering
  • Add not-found.tsx in route segment
react3 fixes

Next.js redirect() in try/catch

Error:.*NEXT_REDIRECT

  • Don't wrap redirect() in try/catch
  • Move redirect outside of try block
react3 fixes

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
react3 fixes

useFormState/useActionState not found

useFormState.*is not a function

  • Import from react-dom (useFormState) or react (useActionState)
  • Update to Next.js 14.1+
react3 fixes

More hooks rendered than previous render

Rendered more hooks than during the previous render

  • Don't call hooks conditionally
  • Move hooks before early returns
react3 fixes

Fewer hooks rendered than expected

Rendered fewer hooks than expected

  • Don't return early before hooks
  • Keep hooks at top of component
react3 fixes

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
react3 fixes

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
react3 fixes

Too many re-renders (infinite loop)

Too many re-renders.*infinite loop

  • Don't call setState in render body
  • Use useEffect with proper deps
react3 fixes

Maximum update depth exceeded

Maximum update depth exceeded

  • Check useEffect dependencies causing re-trigger
  • Memoize objects/arrays in dependencies
react3 fixes

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
react3 fixes

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
react3 fixes

React is null (duplicate React)

Cannot read properties of null.*reading 'useState'

  • Check for duplicate React in node_modules
  • Use npm dedupe
react3 fixes

Suspense boundary needs fallback prop

Suspense.*boundary.*no fallback

  • Add fallback prop to Suspense: <Suspense fallback={<Loading/>}>
  • Provide loading UI component
react3 fixes

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
react3 fixes

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
react3 fixes

Synchronous suspense without transition

A component suspended while responding to synchronous input

  • Wrap state update in startTransition
  • Use useDeferredValue for derived data
react3 fixes

createContext in Server Component

createContext.*server component

  • Move context to client component with 'use client'
  • Use module-level variables for server state
react3 fixes

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
react3 fixes

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
react3 fixes

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'
react3 fixes

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
react3 fixes

generateStaticParams missing for dynamic route

generateStaticParams.*dynamic route.*not found

  • Add generateStaticParams to generate all paths
  • Use dynamicParams = false to limit
react3 fixes

Parallel route missing default.tsx

Parallel routes.*default\.tsx.*not found

  • Add default.tsx to parallel route slot
  • Export default null component for unmatched
react3 fixes

Intercepting route convention error

'intercepting route'.*convention.*\(\.\.\)

  • Use correct convention: (.) same level, (..) one up, (...) root
  • Check folder naming matches convention
react3 fixes

Metadata export in client component

metadata.*cannot.*exported.*client component

  • Remove 'use client' from page with metadata
  • Use generateMetadata in server components only
react3 fixes

React Query: No QueryClient set

useQuery.*No QueryClient set

  • Wrap app with QueryClientProvider
  • Provide QueryClient instance
react3 fixes

React Query: Missing query key

(useMutation|useQuery).*missing.*queryKey

  • Add queryKey array to options
  • Use unique key for each query
react3 fixes

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
react3 fixes

Zustand store access before initialization

zustand.*Cannot access.*before initialization

  • Don't access store at module level
  • Use store inside components/hooks only
react3 fixes

Zustand subscribe with selector issue

zustand.*subscribe.*selector

  • Use useStore(store, selector) pattern
  • Add equality function for object selectors
react3 fixes

Jotai atom not found in Provider scope

jotai.*atom.*not found.*Provider

  • Wrap component tree with Jotai Provider
  • Use default store for providerless mode
react3 fixes

React Hook Form register ref issue

React Hook Form.*register.*ref

  • Use {...register('name')} spread pattern
  • Don't combine ref with register
react3 fixes

React Hook Form: control prop required

(useForm|Controller).*control.*is required

  • Pass control from useForm to Controller
  • Destructure control from useForm()
react3 fixes

React Hook Form state update after unmount

Cannot update.*form state.*unmounted

  • Use shouldUnregister: true option
  • Reset form on unmount
react3 fixes

Radix UI component used outside required context

Radix.*must be used within

  • Wrap with required parent component
  • Check Radix compound component structure
react3 fixes

Radix/shadcn portal rendering issue

(Dialog|Popover|DropdownMenu).*Content.*rendered.*Portal

  • Check z-index of portal container
  • Use modal prop for Dialog
react3 fixes

Radix Slot/asChild expects single child

Slot.*asChild.*must.*single child

  • Pass exactly one child element
  • Don't use Fragment with asChild
react3 fixes

shadcn component not applying className

Component.*not responding to className.*shadcn

  • Use cn() utility to merge classNames
  • Check component accepts className prop
react3 fixes

React 19 Compiler cannot compile hook

React compiler.*cannot compile.*hook

  • Add 'use no memo' directive to opt out
  • Simplify hook logic for compiler
react3 fixes

React 19 Compiler rules violation

React compiler.*rules of react.*violated

  • Don't mutate props or state directly
  • Ensure hooks follow rules of hooks
react3 fixes

useFormStatus not inside form

(useOptimistic|useFormStatus).*not.*descendant.*form

  • Use useFormStatus in component rendered inside <form>
  • Create child component for form status
react3 fixes

Warning: update not wrapped in act()

(Error|Warning).*act\(\).*not wrapped

  • Wrap async state updates in act() during tests
  • Use waitFor from testing-library
react3 fixes

NextAuth session is null/undefined

next-auth.*session.*null.*undefined

  • Wrap with SessionProvider
  • Check getServerSession() in server components
react3 fixes

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
react3 fixes

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
react3 fixes

Server Actions must be async functions

"use server" functions.*must be async

  • Add async keyword to function
  • Server actions must return Promise
react3 fixes

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
react3 fixes

revalidatePath/Tag only on server

(revalidatePath|revalidateTag).*only.*server

  • Call from server action or route handler
  • Don't use in client components
react3 fixes

Dynamic usage in force-static page

Dynamic server usage.*force-static

  • Remove export const dynamic = 'force-static'
  • Move dynamic code to client component
react3 fixes

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
react3 fixes

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
react3 fixes

Server-only exports in client component

(generateMetadata|generateStaticParams).*cannot.*'use client'

  • Remove 'use client' from page with these exports
  • Move to separate server file
react3 fixes

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
react3 fixes

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
react3 fixes

useTransition isPending stuck true

(useTransition|startTransition).*isPending.*stuck

  • Ensure async operation completes or errors
  • Don't throw in transition without error boundary
react3 fixes

useDeferredValue showing stale content

useDeferredValue.*causing.*stale

  • This is expected: shows old value during transition
  • Add visual indicator for pending state
react3 fixes

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
react3 fixes

useImperativeHandle ref is null

useImperativeHandle.*ref.*null

  • Ensure ref is passed from parent with forwardRef
  • Check ref is not conditionally applied
react3 fixes

flushSync called during render

flushSync.*cannot.*during.*render

  • Move flushSync to event handler or useEffect
  • Don't call during component render
react3 fixes

Recoil: Missing RecoilRoot provider

(Recoil|atom).*RecoilRoot.*missing

  • Wrap app with <RecoilRoot>
  • Check provider is above component
react3 fixes

Recoil/Jotai atom circular dependency

(selector|atom).*circular dependency

  • Break circular reference between atoms
  • Use atomFamily for dynamic atoms
react3 fixes

Zustand store not properly created

Cannot read properties.*'subscribe'.*Zustand

  • Use create() from zustand correctly
  • Check store is function, not result of calling it
react3 fixes

Zustand persist: storage is undefined (SSR)

persist.*middleware.*storage.*undefined

  • Use createJSONStorage(() => localStorage) with check
  • Skip hydration on server with skipHydration
react3 fixes

TanStack Query: Suspense query not dehydrated

(useSuspenseQuery|prefetchQuery).*not.*dehydrated

  • Prefetch in server component and dehydrate
  • Use HydrationBoundary with dehydrated state
react3 fixes

TanStack Query mutation onSuccess not firing

Mutation.*onSuccess.*not.*firing

  • Check mutation function doesn't throw
  • Verify onSuccess is in correct options level
react3 fixes

Cannot find next/headers module

Cannot find module 'next/headers'

  • Only import in server components
  • Update Next.js version
react3 fixes

useSearchParams needs Suspense boundary

(useSearchParams|useRouter).*Suspense boundary.*required

  • Wrap component using useSearchParams in Suspense
  • Add fallback for search params loading
react3 fixes

Next.js Image requires width and height

(image|Image).*width.*height.*required

  • Add width and height props
  • Use fill prop for responsive images
react3 fixes

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
react3 fixes

window/document not defined (SSR)

(window|document|localStorage).*not defined

  • Use typeof window !== 'undefined' check
  • Access in useEffect only
react3 fixes

ResizeObserver loop error

ResizeObserver.*loop.*completed.*undelivered notifications

  • This is usually benign and can be ignored
  • Add error boundary to catch
react3 fixes

tRPC: No matching procedure found

(tRPC|createTRPCNext).*No.*matching.*procedure

  • Check procedure name matches router definition
  • Verify router is exported correctly
react3 fixes

Zod validation failed in form/API

(Zod|z\.).*validation.*failed

  • Check input matches Zod schema
  • Handle validation errors with safeParse
react3 fixes

Next.js cache not revalidating

NEXT_CACHE.*stale.*revalidate

  • Use revalidateTag() or revalidatePath()
  • Set revalidate time in fetch options
react3 fixes

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
react3 fixes

Prop value differs between server/client render

Prop.*did not match.*server.*"".*client.*"[^"]+"

  • Use useEffect for client-only prop values
  • Add suppressHydrationWarning
react3 fixes

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
react3 fixes

Unmatched JSX closing tag

Unmatched.*closing tag

  • Match opening and closing JSX tags
  • Check for typos in component names
react3 fixes

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
react3 fixes

useCallback dependency changes every render

useCallback.*dependency.*changes every render

  • Memoize dependency values
  • Move object/array creation outside render
react3 fixes

React Hook missing dependency warning

(exhaustive-deps|React Hook.*missing dependency)

  • Add missing deps to dependency array
  • Use useCallback/useMemo for object deps
react3 fixes

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
react3 fixes

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
react3 fixes

React deprecated API usage

(findDOMNode|legacy context|UNSAFE_).*deprecated

  • Use refs instead of findDOMNode
  • Use new Context API
react3 fixes

Next.js route group layout conflict

route.*group.*\(.*\).*layout.*conflict

  • Ensure route groups don't share layout paths
  • Move shared layout to parent
react3 fixes

Next.js route special files not recognized

(generateSitemaps|generateImageMetadata).*not recognized

  • Check file is in correct directory
  • Verify Next.js version supports the API
react3 fixes

Next.js unstable_cache revalidation issues

unstable_cache.*revalidate.*not working

  • Tag cache entries for revalidation
  • Use revalidateTag after mutation
react3 fixes

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
react3 fixes

Turbopack module resolution failure

(TURBOPACK|turbo).*Module not found

  • Check turbo.json configuration
  • Some packages not yet compatible with Turbopack
react3 fixes

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
react3 fixes

cmdk/Command component not rendering items

(cmdk|Command).*not rendering.*items

  • Check Command.Item key prop
  • Verify filter function returns results
react3 fixes

Sonner/toast not showing notifications

(Sonner|toast).*not showing.*Provider

  • Add <Toaster /> component to layout
  • Check toast import from correct package
react3 fixes

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
react3 fixes

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()}`
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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>`
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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
react3 fixes

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