What causes "请确保企业微信配置唯一性[{corpId}]" in binarywang/WxJava?

Find the corpId named in the message and check every app under that corp.

binarywang/WxJava · error · RuntimeException

请确保企业微信配置唯一性[{corpId}]

Error message

请确保企业微信配置唯一性[{corpId}]

What it means

Thrown by the Solon multi-account WeChat Work (企业微信) auto-configuration. It groups configured apps by `corpId`, then within each corp requires `agentId` to be unique. Duplicate agentId under the same corp would collide on token caches keyed by corpId+agentId. It is a RuntimeException carrying the offending corpId in the message.

Source

Thrown at solon-plugins/wx-java-cp-multi-solon-plugin/src/main/java/com/binarywang/solon/wxjava/cp_multi/configuration/services/AbstractWxCpConfiguration.java:64

     * <p>但同一 corpId 下不允许出现重复的 agentId（包括多个 null）。</p>
     *
     * 查看 {@link me.chanjar.weixin.cp.config.impl.AbstractWxCpInRedisConfigImpl#setAgentId(Integer)}
     */
    Collection<WxCpSingleProperties> corpList = corps.values();
    if (corpList.size() > 1) {
      // 先按 corpId 分组统计
      Map<String, List<WxCpSingleProperties>> corpsMap = corpList.stream()
        .collect(Collectors.groupingBy(WxCpSingleProperties::getCorpId));
      Set<Map.Entry<String, List<WxCpSingleProperties>>> entries = corpsMap.entrySet();
      for (Map.Entry<String, List<WxCpSingleProperties>> entry : entries) {
        String corpId = entry.getKey();
        // 校验每个企业下，agentId 是否唯一
        boolean multi = entry.getValue().stream()
          // 通讯录没有 agentId，使用字符串转换避免 null 与 agentId=0 冲突
          .collect(Collectors.groupingBy(c -> Objects.toString(c.getAgentId(), "null"), Collectors.counting()))
          .entrySet().stream().anyMatch(e -> e.getValue() > 1);
        if (multi) {
          throw new RuntimeException("请确保企业微信配置唯一性[" + corpId + "]");
        }
      }
    }
    WxCpMultiServicesImpl services = new WxCpMultiServicesImpl();

    Set<Map.Entry<String, WxCpSingleProperties>> entries = corps.entrySet();
    for (Map.Entry<String, WxCpSingleProperties> entry : entries) {
      String tenantId = entry.getKey();
      WxCpSingleProperties wxCpSingleProperties = entry.getValue();
      WxCpDefaultConfigImpl storage = this.wxCpConfigStorage(wxCpMultiProperties);
      this.configCorp(storage, wxCpSingleProperties);
      this.configHttp(storage, wxCpMultiProperties.getConfigStorage());
      WxCpService wxCpService = this.wxCpService(storage, wxCpMultiProperties.getConfigStorage());
      services.addWxCpService(tenantId, wxCpService);
    }
    return services;
  }

View on GitHub (pinned to 1c43293a3c)

Solutions

Find the corpId named in the message and check every app under that corp.
Give each app a distinct `agentId`; for multiple contacts-type apps under one corp, you cannot — split them across separate corp configs or instances.
Re-deploy once the duplicate is resolved.

Example fix

// before
wxjava:
  cp:
    apps:
      a: { corpId: ww1, agentId: 1000002 }
      b: { corpId: ww1, agentId: 1000002 }  # duplicate -> throws 请确保企业微信配置唯一性[ww1]
// after
      b: { corpId: ww1, agentId: 1000005 }

Defensive patterns

Strategy: validation

Validate before calling

// Validate corpId+agentId uniqueness before wiring WxCpMultiServicesImpl
Map<String, List<WxCpSingleProperties>> byCorp = corpList.stream()
    .collect(Collectors.groupingBy(WxCpSingleProperties::getCorpId));
for (Map.Entry<String, List<WxCpSingleProperties>> e : byCorp.entrySet()) {
    Set<String> seen = new HashSet<>();
    for (WxCpSingleProperties p : e.getValue()) {
        String key = Objects.toString(p.getAgentId(), "null");
        if (!seen.add(key)) {
            throw new IllegalStateException(
                "Duplicate agentId " + key + " under corp " + e.getKey());
        }
    }
}

Prevention

Keep a single inventory of corpId/agentId pairs and check for duplicates on deploy.
Remember contacts apps share the null-agentId slot — at most one per corp.
Name tenant keys after the agent to make collisions obvious.

When it happens

Trigger: Two tenant entries sharing both the same `corpId` and the same `agentId`. Note: contacts-sync apps legitimately have a null agentId; the code maps null to the string "null" so that two null-agentId entries under one corp are *also* treated as duplicates.

Common situations: Adding a second self-built app under the same enterprise but reusing the agentId; mis-pasting an agentId; configuring two contacts apps (agentId null) for one corp.

Related errors

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