wuyouzhuguli/SpringAll · warning · ValidateCodeException

验证码不能为空！

Error message

验证码不能为空！

What it means

Thrown by ValidateCodeFilter.validateCode when the login POST to /login does not include an 'imageCode' request parameter (blank or absent). It is a ValidateCodeException raised inside the captcha-validation filter that runs before Spring Security authentication; the filter catches it and delegates to AuthenticationFailureHandler. The check is the first of four validation gates (empty -> not-in-session -> expired -> mismatch).

Source

Thrown at 59.Spring-Security-SessionManager/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

  1. Ensure the login request body/form includes a parameter literally named 'imageCode' with the user-typed captcha text.
  2. Verify the front-end <input name="imageCode"> matches the backend ServletRequestUtils.getStringParameter(..., "imageCode").
  3. Confirm the filter only intercepts /login POST so it does not fire on other endpoints that legitimately lack a captcha.
  4. If captcha is optional on some flows, gate validateCode() on the presence of the imageCode param instead of throwing.

Example fix

// before
formData.append("captcha", userTypedCode);

// after
formData.append("imageCode", userTypedCode);
Defensive patterns

Strategy: validation

Validate before calling

// client-side: ensure imageCode present before submit
const code = form.get('imageCode');
if (!code || !code.trim()) { showError('请输入验证码'); return; }

Try / catch

// ValidateCodeFilter already wraps validateCode() in try/catch and routes to
// authenticationFailureHandler; surface the message to the user there.
@Override
public void onAuthenticationFailure(req, res, e) {
    res.getWriter().write(e.getMessage());
}

Prevention

When it happens

Trigger: A POST /login form submission that omits the imageCode field, sends it empty, or names the field something other than 'imageCode'. The filter only runs when requestURI equals '/login' and method is POST.

Common situations: Front-end input named 'captcha' or 'code' instead of 'imageCode'; an AJAX login that forgets to append the captcha value; a form where the captcha field is disabled or hidden; copying a tutorial form whose field name was changed.

Related errors

AI-assisted analysis of wuyouzhuguli/SpringAll@614d2578d9 (2026-08-14). Data as JSON: /api/errors/cd8b8fb14718c821. Report an issue: GitHub.