wuyouzhuguli/SpringAll · error · ValidateCodeException
验证码不能为空！
Error message
验证码不能为空！
What it means
Custom ValidateCodeException thrown inside ValidateCodeFilter.validateCode when the submitted 'imageCode' request parameter is blank. This filter runs before username/password authentication and rejects the request early if the captcha value is missing. It is part of the mrbird Spring Security image-captcha flow (session key SESSION_KEY_IMAGE_CODE).
Source
Thrown at 61.Spring-security-Permission/src/main/java/cc/mrbird/validate/code/ValidateCodeFilter.java:48
protected void doFilterInternal(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse, FilterChain filterChain) throws ServletException, IOException {
if (StringUtils.equalsIgnoreCase("/login", httpServletRequest.getRequestURI())
&& StringUtils.equalsIgnoreCase(httpServletRequest.getMethod(), "post")) {
try {
validateCode(new ServletWebRequest(httpServletRequest));
} catch (ValidateCodeException e) {
authenticationFailureHandler.onAuthenticationFailure(httpServletRequest, httpServletResponse, e);
return;
}
}
filterChain.doFilter(httpServletRequest, httpServletResponse);
}
private void validateCode(ServletWebRequest servletWebRequest) throws ServletRequestBindingException {
ImageCode codeInSession = (ImageCode) sessionStrategy.getAttribute(servletWebRequest, ValidateController.SESSION_KEY_IMAGE_CODE);
String codeInRequest = ServletRequestUtils.getStringParameter(servletWebRequest.getRequest(), "imageCode");
if (StringUtils.isBlank(codeInRequest)) {
throw new ValidateCodeException("验证码不能为空！");
}
if (codeInSession == null) {
throw new ValidateCodeException("验证码不存在！");
}
if (codeInSession.isExpire()) {
sessionStrategy.removeAttribute(servletWebRequest, ValidateController.SESSION_KEY_IMAGE_CODE);
throw new ValidateCodeException("验证码已过期！");
}
if (!StringUtils.equalsIgnoreCase(codeInSession.getCode(), codeInRequest)) {
throw new ValidateCodeException("验证码不正确！");
}
sessionStrategy.removeAttribute(servletWebRequest, ValidateController.SESSION_KEY_IMAGE_CODE);
}
}
View on GitHub (pinned to 614d2578d9)
Solutions
- Ensure the login request includes a non-empty 'imageCode' parameter whose name exactly matches what ValidateCodeFilter reads.
- Check the frontend field name binding: the captcha input must be submitted under the key 'imageCode'.
- If you intentionally want a route to bypass captcha, configure the filter's URL set (the urls check above the validateCode call) so it does not run for that path.
- For API testing with Postman/curl, add -F imageCode=<value> (or the matching param) plus a valid JSESSIONID cookie from /code/image.
Example fix
// before (curl missing captcha) // curl -b cookies.txt -X POST http://host/login -d 'username=admin&password=123456' // after // curl -b cookies.txt -X POST http://host/login -d 'username=admin&password=123456&imageCode=1234'
Defensive patterns
Strategy: validation
Validate before calling
// Before submitting login, ensure the captcha field is present and non-empty.
const imageCode = form.get('imageCode');
if (!imageCode || !imageCode.trim()) {
showError('请输入图片验证码');
return;
}
await fetch('/login', { method:'POST', body: form, credentials:'same-origin' }); Try / catch
// ValidateCodeException is routed to authenticationFailureHandler; map it to a user-facing message.
try { await login(); }
catch (e) {
if (/验证码不能为空/.test(e.message)) showFieldError('imageCode', '验证码不能为空');
else handleError(e);
} Prevention
- Bind the captcha <input name="imageCode"> to the same key the filter reads.
- Disable the submit button until imageCode is non-empty.
- Fetch /code/image with credentials:'same-origin' so the session is shared.
When it happens
Trigger: A POST to the login URL that the filter intercepts where the form body / query string / JSON omits the 'imageCode' parameter, or sends it as empty/whitespace. ServletRequestUtils.getStringParameter(..., "imageCode") returns null/empty and StringUtils.isBlank is true before the session code is even consulted.
Common situations: Frontend form field named differently (verifyCode, captcha, code) instead of 'imageCode'; AJAX/fetch login payload that forgot to append the captcha; Postman/curl testing without the param; the captcha <img> was displayed but its input never bound to the request.
Related errors
AI-assisted analysis of wuyouzhuguli/SpringAll@614d2578d9 (2026-08-14).
Data as JSON: /api/errors/ab5c0ed12613efae.
Report an issue: GitHub.