apache/hadoop · error · IOException

Invalid HTTP PUT operation [{0}]

Error message

Invalid HTTP PUT operation [{0}]

What it means

HttpFSServer.put() switches over the PUT-verb operations (CREATE, MKDIRS, RENAME, SETPERMISSION, SETOWNER, SETREPLICATION, SETTIMES, CREATESNAPSHOT, RENAMEWATCHSNAPSHOT?, SATISFYSTORAGEPOLICY, ...) and throws IOException('Invalid HTTP PUT operation [<op>]') from the default branch otherwise.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/fs/http/server/HttpFSServer.java:1117

      case SETECPOLICY: {
        String policyName = params.get(ECPolicyParam.NAME, ECPolicyParam.class);
        FSOperations.FSSetErasureCodingPolicy command =
            new FSOperations.FSSetErasureCodingPolicy(path, policyName);
        fsExecute(user, command);
        AUDIT_LOG.info("[{}] to policy [{}]", path, policyName);
        response = Response.ok().build();
        break;
    }
    case SATISFYSTORAGEPOLICY: {
      FSOperations.FSSatisyStoragePolicy command =
          new FSOperations.FSSatisyStoragePolicy(path);
      fsExecute(user, command);
      AUDIT_LOG.info("satisfy storage policy for [{}]", path);
      response = Response.ok().build();
      break;
    }
      default: {
        throw new IOException(
          MessageFormat.format("Invalid HTTP PUT operation [{0}]",
                               op.value()));
      }
    }
    return response;
  }

}

View on GitHub (pinned to 2add963021)

Solutions

1. Check the op against the PUT set in the WebHDFS/HttpFS REST docs and correct verb or spelling.
2. If the message names a genuinely new op, upgrade the HttpFS server to a Hadoop version that implements it.
3. Test with curl -X PUT '<url>&op=<OP>' first to isolate client-library behavior.

Example fix

# before
$ curl -X PUT 'http://host:14000/webhdfs/v1/tmp/f?op=APPEND&user.name=alice'

# after
$ curl -X POST 'http://host:14000/webhdfs/v1/tmp/f?op=APPEND&user.name=alice' --data-binary @localfile

Set<String> PUT_OPS = Set.of("CREATE","MKDIRS","RENAME","SETPERMISSION","SETOWNER",
    "SETREPLICATION","SETTIMES","CREATESNAPSHOT","RENAME_SNAPSHOT".replace('_',''),
    "SETREPLICATION","SETSTORAGEPOLICY","SATISFYSTORAGEPOLICY","SETECPOLICY");
if (!PUT_OPS.contains(op)) {
  throw new IllegalArgumentException(op + " is not a PUT operation on this server");
}

static boolean isValidPutOp(String op) {
  return Set.of("CREATE","MKDIRS","RENAME","SETPERMISSION","SETOWNER",
    "SETREPLICATION","SETTIMES","CREATESNAPSHOT","RENAMESNAPSHOT",
    "SETSTORAGEPOLICY","SATISFYSTORAGEPOLICY","SETECPOLICY").contains(op);
}

try {
  resp = http.put(buildUrl(op));
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("Invalid HTTP PUT operation")) {
    throw new IllegalArgumentException("Wrong verb or unsupported op " + op, e);
  }
  throw e;
}

When it happens

Trigger: PUT ?op=DELETE (a DELETE op); PUT ?op=SATISFYSTORAGEPOLICY on a server older than the storage-policy-satisfy feature; PUT ?op=SETPOLICY (typo for SETSTORAGEPOLICY); PUT ?op=APPEND (a POST op).

Common situations: Feature-gated ops (satisfyStoragePolicy, EC policies) sent to older HttpFS during mixed-version clusters; scripts ported between Hadoop versions; monospelled op parameters; REST frameworks that force PUT for all mutations.

Related errors

• Invalid HTTP GET operation [{0}]
• Invalid HTTP DELETE operation [{0}]
• Invalid HTTP POST operation [{0}]
• {str} is not a valid PUT operation.
• Operation [{0}], invalid path [{1}], must be '/'

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