Skip to content

docs: clarify ES version compatibility and downgrade guidance #4568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jan-Kazlouski-elastic merged 2 commits into from
Oct 6, 2026
Merged

docs: clarify ES version compatibility and downgrade guidance #4568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c78054
docs: clarify ES version compatibility and downgrade guidance
Jan-Kazlouski-elastic Oct 6, 2026
4a6a6b1
Update NOTICE.txt
elasticmachine Oct 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,22 +98,25 @@ The framework serves two distinct, but related use cases:
### Version compatibility with Elasticsearch

> [!NOTE]
> Version compatibility will not be checked if Elasticsearch is serverless.

The Connector will perform a version compatibility check with the configured Elasticsearch server on startup.
If the versions are incompatible, the Connector will terminate and output the incompatible versions in the shell.
If the versions are different but otherwise compatible, the Connector will output a warning in the shell but will continue operating.

We recommend running on the same version as Elasticsearch.
However, if you want to hold back upgrading one or the other for any reason, use this table to determine if your versions will be compatible.

| Situation | Example Connector Framework version | Example ES version | Outcome |
|---------------------------------|-------------------------------------|--------------------| ------- |
| Versions are the same. | 8.15.1.0 | 8.15.1 | 💚 OK |
| Connectors has a build version. | 8.15.1.3 | 8.15.1 | 💚 OK |
| ES patch number is newer. | 8.15.__0__.0 | 8.15.__1__ | ⚠️ Logged warning |
| ES minor number is newer. | 8.__14__.2.0 | 8.__15__.0 | ⚠️ Logged warning |
| ES major number is newer. | __8__.15.1.0 | __9__.0.0 | 🚫 Fatal error |
| ES patch number is older. | 8.15.__1__.0 | 8.15.__0__ | ⚠️ Logged warning |
| ES minor number is older. | 8.__15__.1.0 | 8.__14__.2 | 🚫 Fatal error |
| ES major number is older. | __9__.0.0.0 | __8__.15.1 | 🚫 Fatal error |
> Version compatibility is not checked when Elasticsearch is **serverless** (the connector service skips the check on startup).

The connector service compares its version to the configured Elasticsearch server on startup.
If the versions are incompatible, the service exits and logs the mismatch.
If the versions differ but are compatible, the service logs a warning and continues.

We recommend running the connector service on the same stack version as Elasticsearch.
Use this table to decide whether a deliberate version skew is supported.

Do **not downgrade** the connector service to an older release than the one used when connectors were created.
If you downgrade anyway, connector configuration stored in Elasticsearch may no longer match what the older service expects — you may need to **recreate** affected connectors.

| Situation | Example connector version | Example ES version | Outcome |
|-----------|---------------------------|--------------------|---------|
| Versions match | 8.15.1.0 | 8.15.1 | OK |
| Connector has a build suffix | 8.15.1.3 | 8.15.1 | OK |
| ES patch is newer | 8.15.__0__.0 | 8.15.__1__ | Warning |
| ES minor is newer | 8.__14__.2.0 | 8.__15__.0 | Warning |
| ES major is newer | __8__.15.1.0 | __9__.0.0 | Fatal error |
| ES patch is older | 8.15.__1__.0 | 8.15.__0__ | Warning |
| ES minor is older | 8.__15__.1.0 | 8.__14__.2 | Fatal error |
| ES major is older | __9__.0.0.0 | __8__.15.1 | Fatal error |
4 changes: 2 additions & 2 deletions app/connectors_service/NOTICE.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4241,7 +4241,7 @@ Apache Software License


google-auth
2.59.1
2.60.0
Apache Software License
Apache License
Version 2.0, January 2004
Expand Down Expand Up @@ -7114,7 +7114,7 @@ THE SOFTWARE.


pyspnego
0.12.3
0.12.4
MIT
MIT License

Expand Down
3 changes: 3 additions & 0 deletions docs/UPGRADING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ As Elastic adds new features to the framework, internal classes are renamed, mov
Periodically, the [connector protocol](./CONNECTOR_PROTOCOL.md) changes.
If you find a change that needs to be made at the framework level, [submit a PR](./CONTRIBUTING.md#pull-request-etiquette) for the fix, so that your branch does not differ from the Elastic-maintained remote.

### Version compatibility with Elasticsearch
See [Version compatibility with Elasticsearch](../README.md#version-compatibility-with-elasticsearch) in the repository README (including serverless and supported version skew). Do not downgrade the connector service below the version used when connectors were configured.

### Upgrade all stack components beforehand
Before upgrading `connectors`, you should first stop your running connectors services, upgrade-and-start Elasticsearch, upgrade-and-start Enterprise Search, upgrade-and-start Kibana, and only then upgrade-and-start `connectors`.
As a part of Enterprise Search, the connectors framework's data migrations live inside Enterprise Search.
Expand Down
Loading