apache/hadoop · error · IllegalArgumentException

{str} is not a valid POST operation.

Error message

{str} is not a valid POST operation.

What it means

PostOpParam parses the 'op' query parameter of WebHDFS/HttpFS POST requests against the Op enum in PostOpParam.java:25-36: APPEND, CONCAT, TRUNCATE, UNSETECPOLICY, UNSETSTORAGEPOLICY, NULL. Matching is case-insensitive (Enum.valueOf after upper-casing); any other string throws this IllegalArgumentException, returned to the client as HTTP 400.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/PostOpParam.java:92

      return NAME + "=" + this;
    }
  }

  private static final Domain<Op> DOMAIN = new Domain<>(NAME, Op.class);

  /**
   * Constructor.
   * @param str a string representation of the parameter value.
   */
  public PostOpParam(final String str) {
    super(DOMAIN, getOp(str));
  }

  private static Op getOp(String str) {
    try {
      return DOMAIN.parse(str);
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(str + " is not a valid " + Type.POST
          + " operation.");
    }
  }

  @Override
  public String getName() {
    return NAME;
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Use exactly APPEND, CONCAT, TRUNCATE, UNSETECPOLICY or UNSETSTORAGEPOLICY as the op value on POST.
2. Move misplaced ops to the right verb: SETSTORAGEPOLICY/SETECPOLICY are PUT; their UNSET twins are POST.
3. If the request is from the Java client, upgrade hadoop-hdfs-client to match the server — the client emits correct verb/op pairs.
4. Echo the failing URL in your logs to spot template typos immediately.

Example fix

# before
curl -i -X POST "http://nn:9870/webhdfs/v1/f?op=SETSTORAGEPOLICY"
# after
curl -i -X PUT  "http://nn:9870/webhdfs/v1/f?op=SETSTORAGEPOLICY&policyname=HOT"
curl -i -X POST "http://nn:9870/webhdfs/v1/f?op=UNSETSTORAGEPOLICY"

private static final Set<String> POST_OPS = Set.of("APPEND","CONCAT","TRUNCATE","UNSETECPOLICY","UNSETSTORAGEPOLICY");
static String checkedPostOp(String op) {
  String v = op.toUpperCase(Locale.ROOT);
  if (!POST_OPS.contains(v)) throw new IllegalArgumentException("op must be one of " + POST_OPS + ": " + op);
  return v;
}

static boolean isValidPostOp(String op) {
  return op != null && Set.of("APPEND","CONCAT","TRUNCATE","UNSETECPOLICY","UNSETSTORAGEPOLICY").contains(op.toUpperCase(Locale.ROOT));
}

When it happens

Trigger: POST ?op=APPENDFILE (typo); POST ?op=SETSTORAGEPOLICY (a PUT op — must not be POSTed); POST ?op=CONCAT missing valid sources; POST ?op=UNSETECPOLICY on an older Hadoop that lacks EC support; any op from the GET/PUT/DELETE families sent with the POST verb.

Common situations: The storage-policy and EC unset operations moved verb families between docs versions (some examples show PUT); hand-rolled REST clients hard-coding the wrong verb; CONCAT workflows where the sources list is built dynamically and the op string is templated.

Related errors

• {str} is not a valid DELETE operation.
• {str} is not a valid GET operation.
• {str} is not a valid PUT operation.
• Storage policy name is empty.
• {} is not supported

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/010c708641a2fc3c. Report an issue: GitHub.