What causes "object.getString("error_description")" in justauth/JustAuth?

Open the GitLab application settings and confirm the callback URL equals AuthConfig.redirectUri exactly.

justauth/JustAuth · error · AuthException

object.getString("error_description")

Error message

object.getString("error_description")

What it means

First branch of AuthGitlabRequest.checkResponse(): a GitLab token-endpoint failure is signaled by an 'error' key (standard OAuth2 envelope), and JustAuth throws AuthException with 'error_description' - e.g. 'invalid_grant' plus explanation from GitLab.

Source

Thrown at src/main/java/me/zhyd/oauth/request/AuthGitlabRequest.java:75

            .uuid(object.getString("id"))
            .username(object.getString("username"))
            .nickname(object.getString("name"))
            .avatar(object.getString("avatar_url"))
            .blog(object.getString("web_url"))
            .company(object.getString("organization"))
            .location(object.getString("location"))
            .email(object.getString("email"))
            .remark(object.getString("bio"))
            .gender(AuthUserGender.UNKNOWN)
            .token(authToken)
            .source(source.toString())
            .build();
    }

    private void checkResponse(JSONObject object) {
        // oauth/token 验证异常
        if (object.containsKey("error")) {
            throw new AuthException(object.getString("error_description"));
        }
        // user 验证异常
        if (object.containsKey("message")) {
            throw new AuthException(object.getString("message"));
        }
    }

    /**
     * 返回带{@code state}参数的授权url，授权回调时会带上这个{@code state}
     *
     * @param state state 验证授权流程的参数，可以防止csrf
     * @return 返回授权地址
     * @since 1.11.0
     */
    @Override
    public String authorize(String state) {
        return UrlBuilder.fromBaseUrl(super.authorize(state))
            .queryParam("scope", this.getScopes("+", false, AuthScopeUtils.getDefaultScopes(AuthGitlabScope.values())))

View on GitHub (pinned to 694bbf1b01)

Solutions

Open the GitLab application settings and confirm the callback URL equals AuthConfig.redirectUri exactly.
Re-copy the Application ID and Secret after any app change.
Handle 'invalid_grant' on refresh by deleting stored tokens and sending the user through authorize() again.
For self-hosted instances, verify the instance is reachable over HTTPS with a valid certificate - token exchange fails otherwise.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    return gitlabRequest.getAccessToken(callback);
} catch (AuthException e) {
    String m = String.valueOf(e.getErrorMsg());
    if (m.contains("redirect")) {
        throw new ConfigurationException("GitLab callback URL mismatch - check application settings", e);
    }
    if (m.contains("invalid_grant")) {
        return redirectToReauthorize();
    }
    throw e;
}

Prevention

For self-hosted GitLab, configure the external_url exactly as used in AuthSource and the app callback.
Store refresh tokens; on 'invalid_grant' during refresh, clear sessions and re-authorize instead of retrying.
Verify TLS certificates on self-hosted instances - failed cert validation surfaces as token-endpoint errors.

When it happens

Trigger: getAccessToken()/refresh() with wrong application id/secret, redirect URI not in the GitLab app's trusted list, or an expired/replayed authorization code - GitLab returns {"error":"...","error_description":"..."}.

Common situations: Self-hosted GitLab where the callback URL was configured on a different external URL than the one in AuthConfig; application secret regenerated; user revoked the application so refresh tokens no longer work.

Related errors

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