prestodb/presto · error · PageTransportErrorException

Expected %s header

Error message

Expected %s header

What it means

Every pages response must carry the X-Presto-Task-Instance-Id header so the client can pin subsequent requests to the same worker task instance. When the header is missing the client cannot verify response identity, so it throws PageTransportErrorException with 'Expected X-Presto-Task-Instance-Id header'.

Source

Thrown at presto-spark-base/src/main/java/com/facebook/presto/spark/execution/http/PrestoSparkHttpTaskClient.java:813

            }
        }

        private static ListMultimap<OkHttpHeaderName, String> convertHeaders(Response response)
        {
            ImmutableListMultimap.Builder<OkHttpHeaderName, String> builder = ImmutableListMultimap.builder();
            for (String name : response.headers().names()) {
                for (String value : response.headers().values(name)) {
                    builder.put(OkHttpHeaderName.of(name), value);
                }
            }
            return builder.build();
        }

        private static String getTaskInstanceId(Request request, Response response)
        {
            String taskInstanceId = response.header(PRESTO_TASK_INSTANCE_ID);
            if (taskInstanceId == null) {
                throw new PageTransportErrorException(HostAddress.fromUri(request.url().uri()), format("Expected %s header", PRESTO_TASK_INSTANCE_ID));
            }
            return taskInstanceId;
        }

        private static long getToken(Request request, Response response)
        {
            String tokenHeader = response.header(PRESTO_PAGE_TOKEN);
            if (tokenHeader == null) {
                throw new PageTransportErrorException(HostAddress.fromUri(request.url().uri()), format("Expected %s header", PRESTO_PAGE_TOKEN));
            }
            return Long.parseLong(tokenHeader);
        }

        private static long getNextToken(Request request, Response response)
        {
            String nextTokenHeader = response.header(PRESTO_PAGE_NEXT_TOKEN);
            if (nextTokenHeader == null) {
                throw new PageTransportErrorException(HostAddress.fromUri(request.url().uri()), format("Expected %s header", PRESTO_PAGE_NEXT_TOKEN));

View on GitHub (pinned to 55bb57d202)

Solutions

1. Log the full response headers of the failing request to confirm what the server sent.
2. Verify the request reached a genuine Presto native worker on the correct port.
3. Check whether a proxy or service mesh strips unrecognized X-Presto-* headers and exempt them.
4. Align Presto client and worker versions so the response contract matches.
5. Retry after a worker replacement — a half-dead worker can answer without the full header set.

// validate required headers before trusting the response
String taskId = response.header("X-Presto-Task-Instance-Id");
if (taskId == null) throw new IOException("Response missing task-instance-id from " + request.url());

boolean hasTaskInstanceId(Response r) {
    return r.header("X-Presto-Task-Instance-Id") != null;
}

try {
    client.getPagesRequest(...);
} catch (PageTransportErrorException e) {
    if (e.getMessage().contains("X-Presto-Task-Instance-Id")) {
        // endpoint is not a worker or headers are stripped: re-route/retry
    }
    throw e;
}

When it happens

Trigger: The server responds with correct content type but omits the PRESTO_TASK_INSTANCE_ID header — typically a non-worker component answered the request, or a worker built/patched without the header-writing code.

Common situations: Intermediary stripping custom X-Presto-* headers; wrong service listening on the worker port (e.g. an HTTP health endpoint); mixed Presto versions where the response protocol differs; request hitting a stale decommissioned endpoint.

Related errors

• No Content-Type set in response from remote Presto server
• shuffleWriteInfo and broadcastBasePath can not be specified
• Error reading response from server
• Expected response code to be 200, but was %s:%n%s
• %s header is not set: %s

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/c66a400344320958. Report an issue: GitHub.