justauth/JustAuth · error · AuthException

5016

5016

Error message

Illegal wechat agent id

What it means

AuthWeChatEnterpriseQrcodeV2Request.checkConfig validates the AuthConfig after the standard checks: when loginType equals "CorpApp" (enterprise self-built app mode), agentId must be non-empty, otherwise it throws AuthException with AuthResponseStatus.ILLEGAL_WECHAT_AGENT_ID (code 5016). The agentid is required because the v2 enterprise QR authorize URL embeds it as a query parameter.

Source

Thrown at src/main/java/me/zhyd/oauth/request/AuthWeChatEnterpriseQrcodeV2Request.java:48

    public String authorize(String state) {
        return UrlBuilder.fromBaseUrl(source.authorize())
            .queryParam("login_type", config.getLoginType())
            // 登录类型为企业自建应用/服务商代开发应用时填企业 CorpID，第三方登录时填登录授权 SuiteID
            .queryParam("appid", config.getClientId())
            // 企业自建应用/服务商代开发应用 AgentID，当login_type=CorpApp时填写
            .queryParam("agentid", config.getAgentId())
            .queryParam("redirect_uri", GlobalAuthUtils.urlEncode(config.getRedirectUri()))
            .queryParam("state", getRealState(state))
            .queryParam("lang", config.getLang())
            .build()
            .concat("#wechat_redirect");
    }

    @Override
    protected void checkConfig(AuthConfig config) {
        super.checkConfig(config);
        if ("CorpApp".equals(config.getLoginType()) && StringUtils.isEmpty(config.getAgentId())) {
            throw new AuthException(AuthResponseStatus.ILLEGAL_WECHAT_AGENT_ID, source);
        }
    }
}

View on GitHub (pinned to 694bbf1b01)

Solutions

1. Set agentId in AuthConfig to the numeric agent id of your enterprise self-built app (found in WeChat Work admin console > 应用管理 > the app's AgentId).
2. If you are actually a third-party service provider (服务商), set loginType to "ServiceProvider" instead of "CorpApp".
3. Fail fast at startup: validate the config (loginType/agentId pair) when building the AuthRequest rather than at authorize time.

Example fix

// before
AuthConfig cfg = AuthConfig.builder()
    .clientId("ww1234 corpId").clientSecret("secret")
    .redirectUri("https://app.example.com/wx/callback")
    .loginType("CorpApp")
    .build(); // agentId missing -> 5016

// after
AuthConfig cfg = AuthConfig.builder()
    .clientId("ww1234corpId").clientSecret("secret")
    .redirectUri("https://app.example.com/wx/callback")
    .loginType("CorpApp")
    .agentId("1000002")
    .build();

// fail fast at startup, not at authorize time
void validateWeChatWorkV2(AuthConfig c) {
    if ("CorpApp".equals(c.getLoginType()) && StringUtils.isEmpty(c.getAgentId())) {
        throw new IllegalArgumentException("agentId is required when loginType=CorpApp");
    }
}

try {
    String url = request.authorize(state);
} catch (AuthException e) {
    if (e.getCode() == 5016) throw new ConfigurationException("WeChat Work: set agentId for CorpApp login", e);
    throw e;
}

When it happens

Trigger: Constructing AuthWeChatEnterpriseQrcodeV2Request (or calling authorize on it) with loginType="CorpApp" but AuthConfig.agentId null/empty. Occurs at request creation/authorization time, before any HTTP call.

Common situations: Copy-pasting a WeChat enterprise config from the (non-v2) qrcode request where agentId was optional in third-party ('ServiceProvider'/'第三方') mode; forgetting to set agentId for self-built apps; reading agentId from an env var that is unset in the deployed environment.

Related errors

• 5001
• 5005
• ${errmsg}
• 企业微信获取token失败
• ${errmsg}

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