What causes "ApiSignatureRsaPrivateKeySn不能为空，请检查配置" in binarywang/WxJava?

Set the RSA key serial number: wxMaConfig.setApiSignatureRsaPrivateKeySn(serialNumber)

binarywang/WxJava · error · SecurityException

ApiSignatureRsaPrivateKeySn不能为空，请检查配置

Error message

ApiSignatureRsaPrivateKeySn不能为空，请检查配置

What it means

Thrown as SecurityException when ApiSignatureRsaPrivateKeySn is null or empty in postWithSignature(). This serial number identifies the RSA key pair used for the WeChat API signature (加密网络通道) feature that signs outgoing requests with RSA-PSS. The serial number must be registered with WeChat when uploading the public key.

Source

Thrown at weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/BaseWxMaServiceImpl.java:949

   * @param timestamp 签名时的时间戳
   * @param postData  加密后的请求 POST 数据（JSON 字符串）
   * @return 拼接好的待签名串
   * @see <a href="https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/getting_started/api_signature.html">微信服务端API签名指南</a>
   */
  static String buildSignaturePayload(String urlPath, String appId, long timestamp, String postData) {
    return urlPath + "\n" + appId + "\n" + timestamp + "\n" + postData;
  }

  @Override
  public String postWithSignature(String url, JsonObject jsonObject) throws WxErrorException {
    long timestamp = System.currentTimeMillis() / 1000;
    String appId = this.getWxMaConfig().getWechatMpAppid();
    String rndStr = UUID.randomUUID().toString().replace("-", "").substring(0, 30);
    String aesKey = this.getWxMaConfig().getApiSignatureAesKey();
    String aesKeySn = this.getWxMaConfig().getApiSignatureAesKeySn();
    String rsaKeySn = this.getWxMaConfig().getApiSignatureRsaPrivateKeySn();
    if (rsaKeySn == null || rsaKeySn.isEmpty()) {
      throw new SecurityException("ApiSignatureRsaPrivateKeySn不能为空，请检查配置");
    }

    jsonObject.addProperty("_n", rndStr);
    jsonObject.addProperty("_appid", appId);
    jsonObject.addProperty("_timestamp", timestamp);

    String plainText = jsonObject.toString();
    log.debug("URL:{}加密前请求数据:{}", url, plainText);
    String urlPath;
    if (url.contains("?")) {
      urlPath = url.substring(0, url.indexOf("?"));
    } else {
      urlPath = url;
    }
    String aad = urlPath + "|" + appId + "|" + timestamp + "|" + aesKeySn;
    byte[] realKey;
    try {
      realKey = Base64.getDecoder().decode(aesKey);

View on GitHub (pinned to 1c43293a3c)

Solutions

Set the RSA key serial number: wxMaConfig.setApiSignatureRsaPrivateKeySn(serialNumber)
Obtain the serial number from the WeChat platform when uploading your RSA public key via the certificate management API
Verify all four API signature fields are set: aesKey, aesKeySn, rsaPrivateKeySn, rsaPrivateKey

Example fix

// before
wxMaConfig.setApiSignatureRsaPrivateKeySn(null);

// after
wxMaConfig.setApiSignatureRsaPrivateKeySn("your-rsa-key-serial-number");

Defensive patterns

Strategy: validation

Validate before calling

// Validate API signature config before calling postWithSignature
String rsaKeySn = wxMaConfig.getApiSignatureRsaPrivateKeySn();
if (rsaKeySn == null || rsaKeySn.isEmpty()) {
  throw new IllegalStateException("ApiSignatureRsaPrivateKeySn is required for postWithSignature");
}
service.postWithSignature(url, jsonObject);

Type guard

private static boolean isApiSignatureConfigReady(WxMaConfig config) {
  return config.getApiSignatureRsaPrivateKeySn() != null
      && !config.getApiSignatureRsaPrivateKeySn().isEmpty();
}

Try / catch

try {
  service.postWithSignature(url, jsonObject);
} catch (SecurityException e) {
  if (e.getMessage().contains("RsaPrivateKeySn")) {
    log.error("API signature RSA serial number not configured");
    // configure it dynamically or fall back to non-signed API
  } else {
    throw e;
  }
}

Prevention

Set all four API signature fields at config time: aesKey, aesKeySn, rsaPrivateKeySn, rsaPrivateKey
Validate configuration completeness in a startup health check before using postWithSignature
Document the full API signature setup process including RSA key upload to WeChat platform

When it happens

Trigger: Calling postWithSignature(url, jsonObject) without having configured apiSignatureRsaPrivateKeySn in the WxMaConfig object.

Common situations: API signature feature not fully configured; serial number field not set after key generation; new feature adoption without completing the RSA key registration with WeChat platform.

Related errors

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