alibaba/Sentinel · warning · RequestException

Only form-encoded post request is supported

Error message

Only form-encoded post request is supported

What it means

The simple-http command center only accepts POST requests with Content-Type application/x-www-form-urlencoded (URL-encoded form). checkContentTypeSupported rejects everything else, and processPostRequest throws RequestException(StatusCode.UNSUPPORTED_MEDIA_TYPE, "Only form-encoded post request is supported"), which is returned to the client as HTTP 415. This is a deliberate protocol restriction, not a bug.

Source

Thrown at sentinel-transport/sentinel-transport-simple-http/src/main/java/com/alibaba/csp/sentinel/transport/command/http/HttpEventTask.java:179

     * @param in
     * @param request
     * @throws RequestException
     * @throws IOException
     */
    protected static void processPostRequest(InputStream in, CommandRequest request)
        throws RequestException, IOException {
        Map<String, String> headerMap = parsePostHeaders(in);

        if (headerMap == null) {
            // illegal request
            CommandCenterLog.warn("Illegal request read: null headerMap");
            throw new RequestException(StatusCode.BAD_REQUEST, "");
        }

        if (headerMap.containsKey("content-type") && !checkContentTypeSupported(headerMap.get("content-type"))) {
            // not supported Content-type
            CommandCenterLog.warn("Request not supported: unsupported Content-Type: " + headerMap.get("content-type"));
            throw new RequestException(StatusCode.UNSUPPORTED_MEDIA_TYPE,
                "Only form-encoded post request is supported");
        }

        int bodyLength = 0;
        try {
            bodyLength = Integer.parseInt(headerMap.get("content-length"));
        } catch (Exception e) {
        }
        if (bodyLength < 1) {
            // illegal request without Content-length header
            CommandCenterLog.warn("Request not supported: no available Content-Length in headers");
            throw new RequestException(StatusCode.LENGTH_REQUIRED, "No legal Content-Length");
        }

        parseParams(readBody(in, bodyLength), request);
    }

    /**

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Send form-encoded bodies: curl -d 'key=value' (curl's default Content-Type) without overriding the header
2. URL-encode rule payloads into form parameters per the handler's expected parameter names
3. If JSON posts are a hard requirement, switch the client to a custom command center implementation or push rules via the datasource (Nacos/Apollo/ZooKeeper) instead of the transport API

Example fix

# before
curl -X POST http://localhost:8719/modifyFlowRules -H 'Content-Type: application/json' -d '[{...}]'

# after
curl -X POST http://localhost:8719/modifyFlowRules -d 'data=%5B%7B...%7D%5D'

// client-side: let the HTTP library set the default form content type
// curl: omit -H 'Content-Type'; Java: URL-encoded form entity
// explicit check before send:
if (!"application/x-www-form-urlencoded".equals(myContentType)) {
    throw new IllegalStateException("simple-http transport requires form encoding");
}

if (status == 415) {
    // re-send as application/x-www-form-urlencoded with urlencoded body
}

When it happens

Trigger: curl -X POST http://host:8719/modifyRules -H 'Content-Type: application/json' -d '{...}' — any JSON, multipart, or text/plain POST to the simple-http command port returns 415 with this message.

Common situations: Dashboard or automation scripts pushing rule changes as JSON to a client using sentinel-transport-simple-http; switching transports (netty-http has different constraints); hand-written integration assuming generic HTTP POST.

Related errors

• No legal Content-Length
• buf index out of range: {bg}, buf.length={len}
• Request body is too big, limit size is 4194304
• Parameter key cannot be empty
• Metadata key cannot be empty

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/232ff694e1ca29eb. Report an issue: GitHub.