What causes "need verify: Click Here " in AlistGo/alist?

Click the verification URL in the error, complete the challenge in the browser, then retry.

need verify: <a target="_blank" href="%s">Click Here</a>

Error message

need verify: <a target="_blank" href="%s">Click Here</a>

What it means

ThunderX driver's copy of the captcha verification gate: when the captcha-token API responds with a non-empty Url, the account must complete interactive verification before a token is granted. The error surfaces the verification link as an HTML <a> so frontends can render a clickable link.

Source

Thrown at drivers/thunderx/util.go:175

		Meta:         metas,
		RedirectUri:  "xlaccsdk01://xbase.cloud/callback?state=harbor",
	}
	var e ErrResp
	var resp CaptchaTokenResponse
	_, err := c.Request(XLUSER_API_URL+"/shield/captcha/init", http.MethodPost, func(req *resty.Request) {
		req.SetError(&e).SetBody(param)
	}, &resp)

	if err != nil {
		return err
	}

	if e.IsError() {
		return &e
	}

	if resp.Url != "" {
		return fmt.Errorf(`need verify: <a target="_blank" href="%s">Click Here</a>`, resp.Url)
	}

	if resp.CaptchaToken == "" {
		return fmt.Errorf("empty captchaToken")
	}

	if c.refreshCTokenCk != nil {
		c.refreshCTokenCk(resp.CaptchaToken)
	}
	c.SetCaptchaToken(resp.CaptchaToken)
	return nil
}

// Request 只有基础信息的请求
func (c *Common) Request(url, method string, callback base.ReqCallback, resp interface{}) ([]byte, error) {
	req := c.client.R().SetHeaders(map[string]string{
		"user-agent":       c.UserAgent,
		"accept":           "application/json;charset=UTF-8",

View on GitHub (pinned to 843d9dc814)

Solutions

Click the verification URL in the error, complete the challenge in the browser, then retry.
Re-login to the ThunderX mount so a fresh captcha token is fetched post-verification.
Keep the device sign stable (persist DeviceID config) to reduce repeat challenges.

Defensive patterns

Strategy: try-catch

Try / catch

if err != nil && strings.Contains(err.Error(), "need verify") {
    url := extractHref(err.Error()) // parse href="%s"
    notifyUser(url)                 // user completes verification, then retry
}

Prevention

Persist device identity across restarts
Handle the verification link as a user-action flow, not a hard failure
Retry the operation once after verification completes

When it happens

Trigger: Any ThunderX login/captcha-token refresh inside drivers/thunderx/util.go where resp.Url != "" — new device sign, changed IP, or expired captcha token during a session.

Common situations: Running ThunderX (the Xunlei international/thunder-x API variant) behind NAT with rotating IPs, container restarts regenerating device IDs, or after Xunlei tightens risk control.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/dfe46d449803b0e4. Report an issue: GitHub.