{"record":{"id":"9e9d755b4ed29b19","repo":"apache/hadoop","slug":"str-is-not-a-valid-put-operation","errorCode":null,"errorMessage":"{str} is not a valid PUT operation.","messagePattern":"(.+?) is not a valid PUT operation\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/PutOpParam.java","lineNumber":125,"sourceCode":"      return NAME + \"=\" + this;\n    }\n  }\n\n  private static final Domain<Op> DOMAIN = new Domain<>(NAME, Op.class);\n\n  /**\n   * Constructor.\n   * @param str a string representation of the parameter value.\n   */\n  public PutOpParam(final String str) {\n    super(DOMAIN, getOp(str));\n  }\n\n  private static Op getOp(String str) {\n    try {\n      return DOMAIN.parse(str);\n    } catch (IllegalArgumentException e) {\n      throw new IllegalArgumentException(str + \" is not a valid \" + Type.PUT\n          + \" operation.\");\n    }\n  }\n\n  @Override\n  public String getName() {\n    return NAME;\n  }\n}\n","sourceCodeStart":107,"sourceCodeEnd":135,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/PutOpParam.java#L107-L135","documentation":"PutOpParam parses the 'op' query parameter of WebHDFS/HttpFS PUT requests against the Op enum in PutOpParam.java:25-63: CREATE, MKDIRS, CREATESYMLINK, RENAME, SETREPLICATION, SETOWNER, SETPERMISSION, SETTIMES, RENEWDELEGATIONTOKEN, CANCELDELEGATIONTOKEN, MODIFYACLENTRIES, REMOVEACLENTRIES, REMOVEDEFAULTACL, REMOVEACL, SATISFYSTORAGEPOLICY, SETACL, SETXATTR, REMOVEXATTR, ENABLEECPOLICY, DISABLEECPOLICY, SETECPOLICY, ALLOWSNAPSHOT, DISALLOWSNAPSHOT, CREATESNAPSHOT, RENAMESNAPSHOT, SETSTORAGEPOLICY, SETQUOTA, SETQUOTABYSTORAGETYPE, NULL. Parsing is case-insensitive; any other value throws this IllegalArgumentException (HTTP 400).","triggerScenarios":"PUT ?op=APPEND or ?op=CONCAT (POST ops); PUT ?op=DELETE (DELETE op); PUT ?op=SETPERM (typo for SETPERMISSION); PUT ?op=SETQUOTA against a pre-3.x NameNode (op added later); PUT ?op=Mkdirs is fine case-wise but 'MKDIR' (missing S) fails.","commonSituations":"Copy-pasting op values across verb families from mixed documentation; older clusters lacking newer ops (SETQUOTA, SETQUOTABYSTORAGETYPE, SATISFYSTORAGEPOLICY, EC ops); templated clients that concat the operation name from user input.","solutions":["Correct the op token to one of the PUT Op constants in PutOpParam.java:25-63 (all-uppercase, exact).","Verify the verb: APPEND/CONCAT/TRUNCATE/UNSET* are POST, DELETE/DELETESNAPSHOT are DELETE.","If the op is a newer one (SETQUOTA, SATISFYSTORAGEPOLICY, SETECPOLICY), confirm the NameNode version supports it; otherwise use the RPC/Java client.","Prefer the webhdfs:// FileSystem client which maps FileSystem API calls to valid op/verb pairs."],"exampleFix":"# before\ncurl -i -X PUT \"http://nn:9870/webhdfs/v1/dir?op=MKDIR\"\n# after\ncurl -i -X PUT \"http://nn:9870/webhdfs/v1/dir?op=MKDIRS\"","handlingStrategy":"validation","validationCode":"private static final Set<String> PUT_OPS = Set.of(\"CREATE\",\"MKDIRS\",\"CREATESYMLINK\",\"RENAME\",\"SETREPLICATION\",\"SETOWNER\",\"SETPERMISSION\",\"SETTIMES\",\"RENEWDELEGATIONTOKEN\",\"CANCELDELEGATIONTOKEN\",\"MODIFYACLENTRIES\",\"REMOVEACLENTRIES\",\"REMOVEDEFAULTACL\",\"REMOVEACL\",\"SATISFYSTORAGEPOLICY\",\"SETACL\",\"SETXATTR\",\"REMOVEXATTR\",\"ENABLEECPOLICY\",\"DISABLEECPOLICY\",\"SETECPOLICY\",\"ALLOWSNAPSHOT\",\"DISALLOWSNAPSHOT\",\"CREATESNAPSHOT\",\"RENAMESNAPSHOT\",\"SETSTORAGEPOLICY\",\"SETQUOTA\",\"SETQUOTABYSTORAGETYPE\");\nstatic String checkedPutOp(String op) {\n  String v = op.toUpperCase(Locale.ROOT);\n  if (!PUT_OPS.contains(v)) throw new IllegalArgumentException(\"op must be one of \" + PUT_OPS + \": \" + op);\n  return v;\n}","typeGuard":"static boolean isValidPutOp(String op, Set<String> clusterSupported) {\n  return op != null && clusterSupported.contains(op.toUpperCase(Locale.ROOT));\n}","tryCatchPattern":null,"preventionTips":["Filter the PUT op vocabulary by target Hadoop version (SETQUOTA/SATISFYSTORAGEPOLICY/EC ops are newer).","Use the Java webhdfs client where possible; it cannot emit verb/op mismatches."],"tags":["webhdfs","http-put","query-param","hdfs","rest-api"],"backgroundTag":"webhdfs-invalid-op-parameter","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}