What causes "Illegal code" in justauth/JustAuth?

Inspect the raw callback URL/query string in your controller and log all params — if the user denied access, surface a friendly 'authorization cancelled' message instead of proceeding.

justauth/JustAuth · error · AuthException

5008

5008

Error message

Illegal code

What it means

Thrown by AuthChecker.checkCode when processing the provider callback: the code that the platform is supposed to return in the callback request is absent. JustAuth reads callback.getCode() (falling back to getAuthorization_code() for Huawei) and refuses to continue without it, since code is the credential exchanged for a token. Code 5008 (ILLEGAL_CODE). Twitter is exempt because its flow passes a token+oauthVerifier instead of code.

Source

Thrown at src/main/java/me/zhyd/oauth/utils/AuthChecker.java:87

     * 校验回调传回的code
     * <p>
     * {@code v1.10.0}版本中改为传入{@code source}和{@code callback}，对于不同平台使用不同参数接受code的情况统一做处理
     *
     * @param source   当前授权平台
     * @param callback 从第三方授权回调回来时传入的参数集合
     * @since 1.8.0
     */
    public static void checkCode(AuthSource source, AuthCallback callback) {
        // 推特平台不支持回调 code 和 state
        if (source == AuthDefaultSource.TWITTER) {
            return;
        }
        String code = callback.getCode();
        if (StringUtils.isEmpty(code) && source == AuthDefaultSource.HUAWEI) {
            code = callback.getAuthorization_code();
        }
        if (StringUtils.isEmpty(code)) {
            throw new AuthException(AuthResponseStatus.ILLEGAL_CODE, source);
        }
    }

    /**
     * 校验回调传回的{@code state}，为空或者不存在
     * <p>
     * {@code state}不存在的情况只有两种：
     * 1. {@code state}已使用，被正常清除
     * 2. {@code state}为前端伪造，本身就不存在
     *
     * @param state          {@code state}一定不为空
     * @param source         {@code source}当前授权平台
     * @param authStateCache {@code authStateCache} state缓存实现
     */
    public static void checkState(String state, AuthSource source, AuthStateCache authStateCache) {
        // 推特平台不支持回调 code 和 state
        if (source == AuthDefaultSource.TWITTER) {
            return;

View on GitHub (pinned to 694bbf1b01)

Solutions

Inspect the raw callback URL/query string in your controller and log all params — if the user denied access, surface a friendly 'authorization cancelled' message instead of proceeding.
Make sure the AuthCallback passed in actually carries the code: for Huawei also populate authorization_code; for Twitter pass oauthToken/oauthVerifier (or use its dedicated callback handling).
Verify the redirectUri registered with the provider matches the endpoint that receives code — a mismatch often causes the provider to redirect to an error path without code.
Check proxies/filters are not consuming or rewriting the query string before your handler.

Example fix

// before
@GetMapping('/oauth/callback/huawei')
public Object callback(AuthCallback callback) {
    return new AuthHuaweiRequest(config, cache).getAccessToken(callback);
}

// after
@GetMapping('/oauth/callback/huawei')
public Object callback(AuthCallback callback) {
    if (StringUtils.isEmpty(callback.getCode())
            && StringUtils.isEmpty(callback.getAuthorization_code())) {
        return "authorization was cancelled or invalid"; // user denied / param lost
    }
    return new AuthHuaweiRequest(config, cache).getAccessToken(callback);
}

Defensive patterns

Strategy: validation

Validate before calling

String code = callback.getCode();
if (StringUtils.isEmpty(code) && source == AuthDefaultSource.HUAWEI) code = callback.getAuthorization_code();
if (StringUtils.isEmpty(code)) {
    // user denied, or param lost — do NOT call getAccessToken
    return redirect("/login?error=cancelled");
}

Try / catch

catch (AuthException e) { if (e.getErrorCode() == AuthResponseStatus.ILLEGAL_CODE.getCode()) { /* treat as user-cancelled / broken callback binding */ } }

Prevention

Log the full callback query string (minus secrets) before invoking the SDK.
Bind callback params explicitly in controllers instead of relying on loose binding.
Handle the provider's 'denied' redirect (error=access_denied) as a first-class route.

When it happens

Trigger: Calling request.getAccessToken(AuthCallback) where the callback object was built from a request missing the code parameter: user clicked 'deny/cancel' on the consent page, the controller mapped /callback but did not bind the code query param (e.g. missing @RequestParam or wrong param name), or for Huawei the code arrived under 'authorization_code' and both getters are empty.

Common situations: Users cancelling the authorization dialog and being redirected back without code (often with error=access_denied instead); Spring/Servlet controllers that read the wrong parameter name or swallow query params; reverse proxies or gateways stripping query strings on the callback route; provider returning oauth_verifier (Twitter-style) to a non-Twitter request; Huawei integrations where the callback param is named authorization_code.

Related errors

AI-assisted analysis of justauth/JustAuth@694bbf1b01 (2026-08-14). Data as JSON: /api/errors/639bf2ac94f64d13. Report an issue: GitHub.