tooolbox/blog/Debugging Zustand State Management Errors in React Applications
troubleshooting2025-01-30Β·12Β·215/348

Debugging Zustand State Management Errors in React Applications

Common Zustand pitfalls including selector performance issues, hydration mismatches, middleware configuration, and state persistence in Next.js applications.

Introduction

Zustand's minimalist API makes it tempting to use without understanding its internal mechanics. After debugging several performance issues and hydration mismatches in Zustand-powered applications, I realized that the library's simplicity hides subtle behaviors that can cause serious problems in production.

This post covers the most common Zustand errors I have encountered, from selector-induced re-renders to server-side rendering issues with Next.js. Understanding these patterns will help you avoid the debugging sessions that consumed hours of my time.

Environment

node --version
# v20.11.0

npm list zustand react next
# zustand@4.5.0
# react@18.2.0
# next@14.0.4

The application structure:

app/
β”œβ”€β”€ store/
β”‚   β”œβ”€β”€ useAuthStore.ts
β”‚   β”œβ”€β”€ useCartStore.ts
β”‚   └── useUIStore.ts
β”œβ”€β”€ components/
β”‚   β”œβ”€β”€ Header.tsx
β”‚   β”œβ”€β”€ Cart.tsx
β”‚   └── Sidebar.tsx
β”œβ”€β”€ pages/
β”‚   β”œβ”€β”€ _app.tsx
β”‚   └── index.tsx
└── package.json

Problem

The first issue was that components subscribed to the entire store were re-rendering on every state change, even when the change was unrelated to the component's display:

// store/useAuthStore.ts
interface AuthState {
  user: User | null;
  token: string | null;
  isLoading: boolean;
  error: string | null;
  login: (credentials: Credentials) => Promise;
  logout: () => void;
}

const useAuthStore = create((set) => ({
  user: null,
  token: null,
  isLoading: false,
  error: null,
  login: async (credentials) => {
    set({ isLoading: true, error: null });
    try {
      const user = await loginUser(credentials);
      set({ user, token: user.token, isLoading: false });
    } catch (error) {
      set({ error: error.message, isLoading: false });
    }
  },
  logout: () => set({ user: null, token: null }),
}));

// Component re-renders when isLoading changes
// even though it only displays the user name
function UserProfile() {
  const user = useAuthStore((state) => state.user);
  return 
{user?.name}
;
}

The second issue was a Next.js hydration mismatch. The store was initialized with different values on the server and client, causing React to throw a hydration error:

Warning: Text content did not match. Server: "0" Client: "3"

The third issue was that the persist middleware was storing functions in localStorage, causing "circular reference" errors:

const useCartStore = create(
  persist(
    (set, get) => ({
      items: [],
      addItem: (item) => set((state) => ({
        items: [...state.items, item],
      })),
      // This function gets serialized to localStorage
      // causing errors
      removeItem: (id) => set((state) => ({
        items: state.items.filter((item) => item.id !== id),
      })),
    }),
    { name: "cart-storage" }
  )
);

Analysis

Zustand re-renders a component when the selector returns a different value. The default comparison uses Object.is(), which means if the selector returns a new object reference on every call, the component re-renders. This is a common issue when the selector creates a new object:

// BAD: Returns a new object reference on every call
const user = useAuthStore((state) => ({
  name: state.user?.name,
  email: state.user?.email,
}));

// GOOD: Returns primitive values that can be compared
const name = useAuthStore((state) => state.user?.name);
const email = useAuthStore((state) => state.user?.email);

The Next.js hydration mismatch occurs because Zustand stores are initialized at module scope, which runs on both server and client. If the store accesses browser APIs (like localStorage) or has time-dependent values, the server and client will have different initial states.

The persist middleware serialization issue happens because JavaScript functions cannot be serialized to JSON. When the middleware tries to serialize the store, it encounters the functions and throws an error.

Solution

Fix selector performance with shallow comparison:

import { useShallow } from "zustand/react/shallow";

// Before: Re-renders on every state change
function UserProfile() {
  const { name, email } = useAuthStore((state) => ({
    name: state.user?.name,
    email: state.user?.email,
  }));
  return (
    

      
{name}

      
{email}

    

  );
}

// After: Only re-renders when name or email changes
function UserProfile() {
  const { name, email } = useAuthStore(
    useShallow((state) => ({
      name: state.user?.name,
      email: state.user?.email,
    }))
  );
  return (
    

      
{name}

      
{email}

    

  );
}

Fix Next.js hydration mismatches with the hydration pattern:

// store/useHydration.ts
import { useEffect, useState } from "react";
import { useAuthStore } from "./useAuthStore";

export function useHydration() {
  const [hydrated, setHydrated] = useState(false);

  useEffect(() => {
    // This will only run on the client
    useAuthStore.persist.rehydrate();
    setHydrated(true);
  }, []);

  return hydrated;
}

// In _app.tsx
import { useHydration } from "../store/useHydration";

function MyApp({ Component, pageProps }) {
  const hydrated = useHydration();

  if (!hydrated) {
    return 
Loading...
;
  }

  return ;
}

Fix the persist middleware by separating serializable state from functions:

// store/useCartStore.ts
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";

interface CartItem {
  id: string;
  name: string;
  quantity: number;
  price: number;
}

interface CartState {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  clearCart: () => void;
  getTotal: () => number;
}

export const useCartStore = create()(
  persist(
    (set, get) => ({
      items: [],
      addItem: (item) =>
        set((state) => {
          const existing = state.items.find((i) => i.id === item.id);
          if (existing) {
            return {
              items: state.items.map((i) =>
                i.id === item.id
                  ? { ...i, quantity: i.quantity + item.quantity }
                  : i
              ),
            };
          }
          return { items: [...state.items, item] };
        }),
      removeItem: (id) =>
        set((state) => ({
          items: state.items.filter((item) => item.id !== id),
        })),
      updateQuantity: (id, quantity) =>
        set((state) => ({
          items: state.items.map((item) =>
            item.id === id ? { ...item, quantity } : item
          ),
        })),
      clearCart: () => set({ items: [] }),
      getTotal: () => {
        return get().items.reduce(
          (sum, item) => sum + item.price * item.quantity,
          0
        );
      },
    }),
    {
      name: "cart-storage",
      storage: createJSONStorage(() => localStorage),
      // Only persist the items array
      partialize: (state) => ({ items: state.items }),
    }
  )
);

Use Zustand devtools for debugging:

import { devtools } from "zustand/middleware";

const useAuthStore = create()(
  devtools(
    (set) => ({
      user: null,
      token: null,
      isLoading: false,
      error: null,
      login: async (credentials) => {
        set({ isLoading: true, error: null }, false, "login/start");
        try {
          const user = await loginUser(credentials);
          set({ user, token: user.token, isLoading: false }, false, "login/success");
        } catch (error) {
          set({ error: error.message, isLoading: false }, false, "login/error");
        }
      },
      logout: () => set({ user: null, token: null }, false, "logout"),
    }),
    { name: "AuthStore" }
  )
);

Lessons Learned

  1. Use useShallow for object selectors to prevent unnecessary re-renders. Primitive selectors rarely cause performance issues.

  2. Always call persist.rehydrate() in a useEffect when using Zustand with Next.js to prevent hydration mismatches.

  3. Use partialize in the persist middleware to exclude functions and non-serializable values from storage.

  4. Enable devtools middleware in development to inspect store state changes in React DevTools.

  5. Split large stores into smaller ones based on domain. A single store with 50+ fields is harder to optimize than multiple focused stores.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.