Zustand persist 직렬화 에러 완벽 해결법

🔍 검색 키워드: Zustand persist 에러, 직렬화 실패, JSON stringify, localStorage 버그, 상태 관리 디버깅

Zustand persist 직렬화 에러 해결법

증상

Zustand의 persist 미들웨어를 사용할 때 다음과 같은 에러가 발생한다:

TypeError: Converting circular structure to JSON
    at JSON.stringify (<anonymous>)
      at persist.ts:42

원인

Zustand persist는 상태를 JSON으로 직렬화하여 localStorage에 저장합니다. 순환 참조, 함수, Date/Map/Set 등 특수 객체, undefined 값이 포함되면 에러가 발생합니다.

해결 방법

방법 1: partialize로 직렬화 가능한 상태만 저장

const useStore = create(
    persist(
        (set) => ({ user: { id: 1, createdAt: new Date() }, count: 0 }),
            {
                  name: 'app-storage',
                        partialize: (state) => ({
                                user: { id: state.user.id, createdAt: state.user.createdAt.toISOString() },
                                        count: state.count,
                                              }),
                                                  }
                                                    )
                                                    );

방법 2: 버전 마이그레이션

const useStore = create(
    persist(
        (set) => ({ version: 2, theme: 'dark' }),
            { name: 'app-storage', version: 2, migrate: (s, v) => v < 2 ? { ...s, version: 2 } : s }
              )
              );

정리표

에러 상황	원인	해결법
Converting circular structure to JSON	순환 참조 객체	partialize로 필드 선택
Unexpected token u in JSON	undefined 값 저장됨	초기값을 null로 설정
함수가 저장되지 않음	JSON 미지원 타입	함수는 상태에서 제외

---

팁: Chrome DevTools → Application → Local Storage에서 저장된 값을 직접 확인하고 JSON.parse()로 유효성을 검사하세요.