binarywang/WxJava · error · WxErrorException

知识助理请求需要配置appid

Error message

知识助理请求需要配置appid

What it means

Thrown by `enrichKnowledgeHeaders` before any Knowledge-assistant request (GET/POST/PUT/DELETE/multipart) when `configStorage.appid` is blank. The Knowledge API signs requests with appid+secretKey, so appid is mandatory. It is a WxErrorException thrown before the HTTP call is made.

Source

Thrown at weixin-java-aispeech/src/main/java/me/chanjar/weixin/aispeech/api/impl/WxAispeechServiceImpl.java:184

    }
    HttpEntity entity = builder.build();
    request.setEntity(entity);
    if (entity.getContentType() != null) {
      request.setHeader("Content-Type", entity.getContentType());
    }
    enrichKnowledgeHeaders(request, "");
    return executeRequest(request);
  }

  protected String executeKnowledgeDelete(String path) throws WxErrorException {
    HttpUriRequestBase request = new HttpUriRequestBase("DELETE", URI.create(configStorage.getKnowledgeApiBaseUrl() + path));
    enrichKnowledgeHeaders(request, "");
    return executeRequest(request);
  }

  private void enrichKnowledgeHeaders(HttpUriRequestBase request, String body) throws WxErrorException {
    if (StringUtils.isBlank(configStorage.getAppid())) {
      throw new WxErrorException("知识助理请求需要配置appid");
    }
    if (StringUtils.isBlank(configStorage.getSecretKey())) {
      throw new WxErrorException("知识助理请求需要配置secretKey");
    }

    String requestId = UUID.randomUUID().toString();
    long timestamp = System.currentTimeMillis() / 1000;
    String nonce = randomNonce();
    String signature = WxAispeechSignUtil.calcKnowledgeSignature(configStorage.getSecretKey(), timestamp, nonce,
      requestId, body);

    request.setHeader("X-APPID", configStorage.getAppid());
    request.setHeader("X-Request-ID", requestId);
    request.setHeader("X-Timestamp", String.valueOf(timestamp));
    request.setHeader("X-Nonce", nonce);
    request.setHeader("X-Signature", signature);
    if (!request.containsHeader("Content-Type")) {
      request.setHeader("Content-Type", ContentType.APPLICATION_JSON.getMimeType());

View on GitHub (pinned to 1c43293a3c)

Solutions

1. Set appid on the config storage: `configStorage.setAppid(...)`.
2. Confirm both appid AND secretKey are configured (secretKey is checked immediately after).
3. Add a startup assertion that knowledge credentials are present if knowledge features are used.

Example fix

// before
service.executeKnowledgeGet("/knowledge/list", null);  // throws
// after
configStorage.setAppid("your-appid");
configStorage.setSecretKey("your-secret");
service.executeKnowledgeGet("/knowledge/list", null);

// Guard knowledge calls: require appid (and secretKey)
if (StringUtils.isBlank(configStorage.getAppid())) {
    throw new IllegalStateException("Knowledge API requires appid to be configured");
}

When it happens

Trigger: Calling any knowledge-assistant operation (list/create/update/delete/upload) without having configured appid on the AI Speech config storage.

Common situations: Only dialog credentials were set up; appid property omitted from config; env var for appid unresolved.

Related errors

• 知识助理请求需要配置secretKey
• X-APPID不能为空
• 响应为空
• X-OPENAI-TOKEN不能为空，请先调用getAccessToken或手动设置
• HmacSHA256 signature failed

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