binarywang/WxJava · error · WxRuntimeException

使用该配置的客户群ID列表，支持5个

Error message

使用该配置的客户群ID列表，支持5个

What it means

Thrown as WxRuntimeException (unchecked) inside addJoinWay when the group join way's chatIdList contains more than 5 entries. WeChat's auto-grouping 'join way' feature supports at most 5 customer group chat IDs per configuration. This is a client-side guard before the HTTP call to ADD_JOIN_WAY.

Source

Thrown at weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpExternalContactServiceImpl.java:887

  public WxCpCustomerAcquisitionStatistic customerAcquisitionStatistic(String linkId, @NonNull Date startTime,
                                                                       @NonNull Date endTime) throws WxErrorException {
    long endTimestamp = endTime.getTime() / 1000L;
    long startTimestamp = startTime.getTime() / 1000L;

    JsonObject o = new JsonObject();
    o.addProperty("link_id", linkId);
    o.addProperty("start_time", startTimestamp);
    o.addProperty("end_time", endTimestamp);

    String url = this.mainService.getWxCpConfigStorage().getApiUrl(CUSTOMER_ACQUISITION_STATISTIC);
    return WxCpCustomerAcquisitionStatistic.fromJson(this.mainService.post(url, o));
  }


  @Override
  public WxCpGroupJoinWayResult addJoinWay(WxCpGroupJoinWayInfo wxCpGroupJoinWayInfo) throws WxErrorException {
    if (wxCpGroupJoinWayInfo.getJoinWay().getChatIdList() != null && wxCpGroupJoinWayInfo.getJoinWay().getChatIdList().size() > 5) {
      throw new WxRuntimeException("使用该配置的客户群ID列表，支持5个");
    }
    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(ADD_JOIN_WAY);

    return WxCpGroupJoinWayResult.fromJson(this.mainService.post(url, wxCpGroupJoinWayInfo.getJoinWay().toJson()));
  }

  @Override
  public WxCpBaseResp updateJoinWay(WxCpGroupJoinWayInfo wxCpGroupJoinWayInfo) throws WxErrorException {
    if (wxCpGroupJoinWayInfo.getJoinWay().getChatIdList() != null && wxCpGroupJoinWayInfo.getJoinWay().getChatIdList().size() > 5) {
      throw new WxRuntimeException("使用该配置的客户群ID列表，支持5个");
    }
    final String url = this.mainService.getWxCpConfigStorage().getApiUrl(UPDATE_JOIN_WAY);
    return WxCpBaseResp.fromJson(this.mainService.post(url, wxCpGroupJoinWayInfo.getJoinWay().toJson()));
  }

  @Override
  public WxCpGroupJoinWayInfo getJoinWay(String configId) throws WxErrorException {
    JsonObject json = new JsonObject();

View on GitHub (pinned to 1c43293a3c)

Solutions

1. Limit the chatIdList to at most 5 entries before calling addJoinWay.
2. If more groups are needed, create multiple join way configurations each covering up to 5 groups.
3. Pre-validate: if (chatIdList != null && chatIdList.size() > 5) trim or split before constructing the join way info.

Example fix

// before
joinWayInfo.getJoinWay().setChatIdList(allChatIds); // 8 groups
service.addJoinWay(joinWayInfo); // throws > 5

// after
joinWayInfo.getJoinWay().setChatIdList(allChatIds.subList(0, 5));
service.addJoinWay(joinWayInfo);

List<String> chatIds = wxCpGroupJoinWayInfo.getJoinWay().getChatIdList();
if (chatIds != null && chatIds.size() > 5) {
    throw new IllegalArgumentException("chatIdList exceeds 5 entries");
}

When it happens

Trigger: Calling addJoinWay with wxCpGroupJoinWayInfo.getJoinWay().getChatIdList() containing more than 5 chat IDs. Happens when a developer tries to associate many customer groups with a single auto-grouping QR code or link.

Common situations: Developer fetches all customer group chat IDs from listGroupChat and passes them all into a single join way configuration without realizing the 5-group cap.

Related errors

• 更新「联系我」方式需要指定configId
• 可填充个数：0 ~ 100。超过100个需分批调用。
• 可填充个数：0 ~ 20。
• 「联系我」使用人数默认限制不超过100人(包括部门展开后的人数)
• userid 不能为空

AI-assisted analysis of binarywang/WxJava@1c43293a3c (2026-08-14). Data as JSON: /api/errors/1fc90adcdaef0570. Report an issue: GitHub.