buildCompatibilityHeaders() forcibly adds compatibility headers even when API versioning is not enabled

[odiaseo]

The bug
In the elastic/elasticsearch-php library, the function buildCompatibilityHeaders($headers) in Elastic\Elasticsearch\Traits\EndpointTrait automatically adds compatible-with headers to all requests. This happens even when API versioning is supposed to be disabled.

• This breaks requests when connecting to Elasticsearch 8.x servers (tested on 8.10 and 8.19) if the client sends Content-Type: application/vnd.elasticsearch+json; compatible-with=8 but the server expects plain application/json.
• There is no option in the client configuration to disable this behaviour.

Expected behavior
When API versioning is disabled (environment variable ELASTIC_CLIENT_APIVERSIONING=1 is not set or false), the client should not add compatible-with headers and should use normal JSON headers (Content-Type: application/json, Accept: application/json).

Current behavior
buildCompatibilityHeaders() overrides headers regardless of the API versioning setting, forcing compatible-with=8 and causing 400 Bad Request errors with:

{
  "error": {
    "root_cause": [
      {
        "type": "media_type_header_exception",
        "reason": "Invalid media-type value on headers [Accept, Content-Type]"
      }
    ],
    "type": "media_type_header_exception",
    "reason": "Invalid media-type value on headers [Accept, Content-Type]",
    "caused_by": {
      "type": "status_exception",
      "reason": "A compatible version is required on both Content-Type and Accept headers if either one has requested a compatible version. Accept=null, Content-Type=application/vnd.elasticsearch+json; compatible-with=8"
    },
    "status": 400
  }
}

Steps to reproduce

1. Use elastic/elasticsearch-php client to connect to an Elasticsearch 8.10 or 8.19 server.
2. Make any request (e.g., search).
3. Observe that the client automatically sends compatible-with=8 headers, causing a 400 Bad Request.

Environment

• Elasticsearch server: 8.10 / 8.19
• elastic/elasticsearch-php: latest 8.19 branch
• PHP version: 8.3

Additional context

• Documentation mentions that setting ELASTIC_CLIENT_APIVERSIONING=1 should enable compatibility mode. However, this environment variable is ignored in the code, so there’s no way to disable forced compatibility headers.

Proposed solution

• Honor the ELASTIC_CLIENT_APIVERSIONING variable, or
• Add a client configuration option to disable buildCompatibilityHeaders() for 8.x servers.

[miso93]

+1 I have same issue

[ezimuel]

@odiaseo first of all, sorry for the very late reply. I'm not familiar with ELASTIC_CLIENT_APIVERSIONING environment variable, there's no mention of it in the Elasticsearch PHP documentation. Where did you find it?
I've did a quick search and find only mentioned in the elasticsearch-js documentation talking about migration to 8.x, here.
We don't use this env variable in elasticsearch-php.

Moreover, when you say that is not working with Elasticsearch 8.10 / 8.19 do you mean on-premise, Elastic Cloud or Serverless?
Can you share the PHP code that fails?
Thanks.

[ezimuel]

@pquentin just reminded me that the ELASTIC_CLIENT_APIVERSIONING is something that we managed in 7.x version of the client, see here. We don't have it in 8.x and 9.x clients.

[odiaseo]

@pquentin @ezimuel The code still checks the ELASTIC_CLIENT_APIVERSIONING environment variable to decide whether to include the compatibility header. However, since the variable was removed in versions 8.x and 8.9, the logic now defaults to always adding the header. This leads to the unexpected response.

To resolve this, either reintroduce the variable or update the logic for 8.x and 9.x to stop adding compatibility headers by default.

[pquentin]

The code still checks the ELASTIC_CLIENT_APIVERSIONING environment variable to decide whether to include the compatibility header.

Which code does that? Can you please provide a link? I'm unable to find it in the 8.19 client.

[odiaseo]

The code still checks the ELASTIC_CLIENT_APIVERSIONING environment variable to decide whether to include the compatibility header.

Which code does that? Can you please provide a link? I'm unable to find it in the 8.19 client.

elasticsearch-php/src/Traits/EndpointTrait.php

Line 182 in 25cf4bc

$value = sprintf(Client::API_COMPATIBILITY_HEADER, $matches[1], $matches[2]);