dromara/Sa-Token · error · SaTokenException
10031
10031
Error message
重置的侦听器集合不可以为空
What it means
SaTokenException (code 10031) thrown by SaTokenEventCenter.setListenerList(List<SaTokenListener>) when the supplied list is null. The event center dispatches login/logout/token lifecycle events to its listener list, so replacing it with null would break all event notification — the null check guards that invariant before assignment.
Source
Thrown at sa-token-core/src/main/java/cn/dev33/satoken/listener/SaTokenEventCenter.java:61
// 默认添加控制台日志侦听器
listenerList.add(new SaTokenListenerForLog());
}
/**
* 获取已注册的所有侦听器
* @return /
*/
public static List<SaTokenListener> getListenerList() {
return listenerList;
}
/**
* 重置侦听器集合
* @param listenerList /
*/
public static void setListenerList(List<SaTokenListener> listenerList) {
if(listenerList == null) {
throw new SaTokenException("重置的侦听器集合不可以为空").setCode(SaErrorCode.CODE_10031);
}
SaTokenEventCenter.listenerList = listenerList;
}
/**
* 注册一个侦听器
* @param listener /
*/
public static void registerListener(SaTokenListener listener) {
if(listener == null) {
throw new SaTokenException("注册的侦听器不可以为空").setCode(SaErrorCode.CODE_10032);
}
listenerList.add(listener);
}
/**
* 注册一组侦听器
* @param listenerList / View on GitHub (pinned to ac2c7f6e94)
Solutions
- Pass a non-null list; to clear all listeners use an empty list: SaTokenEventCenter.setListenerList(new ArrayList<>())
- Fix the upstream initialization so the variable can never be null at the call site
- Prefer the additive API registerListener(...) / registerListenerList(...) instead of replacing the whole list
Example fix
// before
List<SaTokenListener> listeners = maybeNull();
SaTokenEventCenter.setListenerList(listeners); // NPE-guard -> exception 10031
// after
SaTokenEventCenter.setListenerList(
listeners != null ? listeners : new ArrayList<>()); Defensive patterns
Strategy: validation
Validate before calling
if (listenerList == null) { /* do not call setListenerList; build an empty list instead */ }
SaTokenEventCenter.setListenerList(listenerList != null ? listenerList : new ArrayList<>()); Prevention
- Use empty collections instead of null when 'no listeners' is the intent
- Prefer registerListener/registerListenerList over replacing the whole list
- Ensure collector methods never return null (Collections.emptyList() convention)
When it happens
Trigger: Calling SaTokenEventCenter.setListenerList(null) directly, typically from custom framework-integration code or startup customization that builds a listener list and passes a null reference (e.g. a field that was never initialized, or a conditional that yields null).
Common situations: Custom integrations or migration code that swaps the listener list at runtime; a list variable conditionally initialized and null in some environment; copy-pasted setup code where the list construction was removed but the setListenerList call remained.
Related errors
AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14).
Data as JSON: /api/errors/9992ccf3f4447106.
Report an issue: GitHub.