[장애 사례] JBoss 세션 저장 시 NotSerializableException 발생 원인과 해결

[장애 사례] JBoss 세션 저장 시 NotSerializableException 발생 원인과 해결

운영 중 JBoss/WildFly 환경에서 다음과 같은 오류 로그가 출력되는 경우가 있습니다.

java.lang.IllegalArgumentException: java.io.NotSerializableException: aaa.bbb.ccc.ddd.LoginManager

이번 글에서는 이 오류의 발생 원인과 해결 방안을 정리합니다.

---

✅ 에러 요약

• 발생 시점: HttpSession.setAttribute() 호출 시
• 발생 원인: 세션에 저장하려는 객체(LoginManager)가 Serializable을 구현하지 않음
• 환경 조건: 세션 클러스터링(distributable)이 활성화된 상태

---

✅ 클러스터 세션 복제에서 직렬화가 필요한 이유

• WAS 클러스터 구성 시, 세션은 여러 서버 간 공유되어야 함
• 이 때 세션 객체는 네트워크를 통해 직렬화되어 전송됨
• Java에서 직렬화를 위해서는 java.io.Serializable 인터페이스 구현이 필수

---

✅ 실제 로그 예시

java.lang.IllegalArgumentException: java.io.NotSerializableException: aaa.bbb.ccc.ddd.LoginManager
    at org.wildfly.clustering.web.cache.session.coarse.CoarseSessionAttributes.setAttribute(CoarseSessionAttributes.java:76)
    ...
    Caused by: java.io.NotSerializableException: aaa.bbb.ccc.ddd.LoginManager

---

✅ 해결 방법

1. 객체에 Serializable 구현

LoginManager.java 클래스 수정:

public class LoginManager implements Serializable {
    private static final long serialVersionUID = 1L;

    // 필드 및 메서드
}

serialVersionUID는 직렬화 버전 호환을 위한 식별자입니다.

---

2. 직렬화 불가능한 필드는 transient 처리

private transient SomeNonSerializableService service;

transient로 지정된 필드는 직렬화 대상에서 제외됩니다.

---

✅ 추가 점검 항목

항목	체크
web.xml에 <distributable/> 명시 여부	✅
세션에 저장하는 객체 구조 점검	✅
의존 객체들까지 직렬화 가능 여부	✅
필요 이상으로 세션에 저장된 객체 제거	✅

---

✅ 마무리

세션 클러스터링 환경에서 발생하는 NotSerializableException은 매우 흔한 장애 요인입니다.
클러스터 구성 시에는 다음을 꼭 지켜야 합니다:

• 세션 저장 객체는 Serializable을 구현할 것
• 비직렬화 필드는 transient 처리
• 꼭 필요한 데이터만 세션에 저장