TIL

Spring Session + Redis Cluster CROSSSLOT 트러블슈팅

증상

• Spring Session Redis를 사용하는 애플리케이션에서 로그인 직후 500 에러 발생
• 스택트레이스에 다음 에러가 출력

    io.lettuce.core.RedisCommandExecutionException:
    CROSSSLOT Keys in request don't hash to the same slot
  

• 실패 지점은 RedisSessionRepository.saveChangeSessionId() 내부의 RENAME 명령

발생 조건

• 아래 세 조건이 모두 충족될 때 재현됨
  • Redis가 Cluster 모드로 동작 (샤드가 1개여도 cluster 프로토콜이면 해당)
  • Spring Session Redis (spring-session-data-redis) 사용
  • 세션 ID가 바뀌는 시점 — 일반적으로 로그인 직후 HttpSession.changeSessionId() 호출 (session fixation 방어)

원인

• Spring Session은 세션 ID가 바뀔 때 Redis RENAME old-key new-key 명령을 발행
• 기본 키 형식: spring:session:sessions:<UUID>
• Redis Cluster는 RENAME 같은 multi-key 명령은 모든 키가 같은 슬롯에 있어야만 허용 (CROSSSLOT 검사)
• UUID가 달라지면 두 키의 슬롯이 다르게 계산되어 명령이 거부됨

해결: Hash Tag 적용

• Redis Cluster는 키 이름 중 {...} 안 문자열만 슬롯 계산에 사용 (hash tag 규칙)
• 네임스페이스를 {spring:session} 처럼 감싸면 키가 {spring:session}:sessions:<UUID> 가 되어, 모든 세션 키가 동일 슬롯으로 매핑됨
• Spring Boot 프로퍼티 한 줄로 해결

    spring:
      session:
        redis:
          namespace: "{spring:session}"
  

• 또는 Java/Kotlin Config

    @Bean
    SessionRepositoryCustomizer<RedisSessionRepository> customizer() {
        return repo -> repo.setRedisKeyNamespace("{spring:session}");
    }
  

보강 포인트

• 클라이언트 종류(Lettuce, Jedis, Redisson)와 무관 — Redis 프로토콜 레벨 제약이라 어떤 클라이언트로도 동일하게 재현됨
• 영향 받는 환경
  • AWS ElastiCache “Cluster mode enabled”
  • GCP Memorystore for Valkey (클러스터 전용 제품)
  • Redis Enterprise
  • 직접 구성한 Redis Cluster
• 비클러스터(standalone) Redis에서는 RENAME이 슬롯 검사 없이 동작하므로 발생하지 않음
• Hash tag는 비클러스터 환경에서는 그냥 키 이름의 일부로 취급되어 동작 차이 없음 → 모든 환경에 일관 적용해도 무해

사이드 이펙트 (배포 시 주의)

• 키 prefix가 spring:session: → {spring:session}: 로 바뀌므로 기존 세션이 일괄 무효화 → 사용자 재로그인 필요
• 운영 환경 배포 전 사전 공지 권장

한 줄 요약

• Spring Session Redis + Redis Cluster 조합의 default 설정 함정 — 네임스페이스에 hash tag 한 번만 씌우면 끝

---

• https://docs.spring.io/spring-session/reference/configuration/redis.html
• https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags