binarywang/WxJava · warning · IllegalArgumentException

表单字段名不能为空

Error message

表单字段名不能为空

What it means

CommonUploadParam.addFormField rejects a null or blank (whitespace-only) field name before adding it to the multipart form. This is a defensive precondition: a multipart part needs a non-empty name to be meaningful and to be accepted by WeChat endpoints.

Source

Thrown at weixin-java-common/src/main/java/me/chanjar/weixin/common/bean/CommonUploadParam.java:93

   * @param name  参数名，如：media
   * @param bytes 字节数组
   * @return 文件上传参数对象
   */
  @SneakyThrows
  public static CommonUploadParam fromBytes(String name, @Nullable String fileName, byte[] bytes) {
    return new CommonUploadParam(name, new CommonUploadData(fileName, new ByteArrayInputStream(bytes), bytes.length), null);
  }

  /**
   * 添加额外的表单字段
   *
   * @param fieldName  表单字段名
   * @param fieldValue 表单字段值
   * @return 当前对象，支持链式调用
   */
  public CommonUploadParam addFormField(String fieldName, String fieldValue) {
    if (fieldName == null || fieldName.trim().isEmpty()) {
      throw new IllegalArgumentException("表单字段名不能为空");
    }
    if (fieldValue == null) {
      throw new IllegalArgumentException("表单字段值不能为null");
    }
    if (this.formFields == null) {
      this.formFields = new HashMap<>();
    }
    this.formFields.put(fieldName, fieldValue);
    return this;
  }

  @Override
  public String toString() {
    return String.format("{name:%s, data:%s, formFields:%s}", name, data, formFields);
  }
}

View on GitHub (pinned to 1c43293a3c)

Solutions

1. Ensure the field name is a non-blank literal or sourced from validated config.
2. If the field is optional, skip the addFormField call entirely instead of passing an empty name.
3. Add a guard/log before the call to catch null or blank names during development.

Example fix

// before
param.addFormField(System.getProperty("form.field"), value); // null if unset

// after
String name = System.getProperty("form.field");
if (name != null && !name.trim().isEmpty()) {
  param.addFormField(name, value);
}

if (fieldName == null || fieldName.trim().isEmpty()) {
  // skip optional field, or throw a clearer domain error
} else {
  param.addFormField(fieldName, fieldValue);
}

try {
  param.addFormField(name, value);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("表单字段名不能为空")) {
    // fix or skip the field
  }
  throw e;
}

When it happens

Trigger: Calling addFormField(null, value) or addFormField(" ", value) while building a CommonUploadParam for an upload request.

Common situations: Field name read from a config/properties file that resolved to null or unset; dynamically generated field names where the generator returned empty; copy-paste leaving a placeholder blank.

Related errors

• 表单字段值不能为null
• uri参数中不允许有access_token: {uri}
• setAttribute: name parameter cannot be null
• 非法请求参数，有部分参数为空 :
• 更新「联系我」方式需要指定configId

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