[[breaking-changes-5.0]]
== Breaking changes in 5.0

This section discusses the changes that you need to be aware of when migrating
your application to Elasticsearch 5.0.

[IMPORTANT]
.Known networking bug in 5.0.0-alpha5
======================================================

There is a major bug in the new Netty4 implementation in this release which
affects any REST requests greater than 1024 bytes in size, and which will
generate an exception similar to the following:

[source,txt]
----
[WARN ][http.netty4] [wtOV9Vb] caught exception while handling client http traffic, closing connection [id: 0x1320b717, L:/0:0:0:0:0:0:0:1:9200 - R:/0:0:0:0:0:0:0:1:54732]
java.lang.UnsupportedOperationException: unsupported message type: DefaultFullHttpResponse (expected: ByteBuf, FileRegion)
----

This is due to incorrect handling of the `Expect` HTTP header, and it can be
worked around in one of three ways:

* Use a client which does not add `Expect` headers (including the official clients).

* Pass a blank `Except` header, e.g.
+
[source,sh]
----
curl -H 'Expect:' ...
----

* Use Netty3 for the HTTP layer by passing the following setting at startup:
+
[source,sh]
----
./bin/elasticsearch -Ehttp.type=netty3
----

======================================================

[float]
[[migration-plugin]]
=== Migration Plugin

The https://github.com/elastic/elasticsearch-migration/blob/2.x/README.asciidoc[`elasticsearch-migration` plugin]
(compatible with Elasticsearch 2.3.0 and above) will help you to find issues
that need to be addressed when upgrading to Elasticsearch 5.0.

[float]
=== Indices created before 5.0

Elasticsearch 5.0 can read indices created in version 2.0 or above.  An
Elasticsearch 5.0 node will not start in the presence of indices created in a
version of Elasticsearch before 2.0.

[IMPORTANT]
.Reindex indices from Elasticseach 1.x or before
=========================================

Indices created in Elasticsearch 1.x or before will need to be reindexed with
Elasticsearch 2.x in order to be readable by Elasticsearch 5.x. It is not
sufficient to use the <<indices-upgrade,`upgrade`>> API.  The easiest
way to reindex old indices is to upgrade to Elasticsearch 2.3 or later and to use the
`reindex` API, or the reindex UI provided by the <<migration-plugin,Migration Plugin>>.

=========================================

The first time Elasticsearch 5.0 starts, it will automatically rename index
folders to use the index UUID instead of the index name. If you are using
<<indices-shadow-replicas,shadow replicas>> with shared data folders, first
start a single node with access to all data folders, and let it rename all
index folders before starting other nodes in the cluster.

[float]
=== Also see:

* <<breaking_50_search_changes>>
* <<breaking_50_mapping_changes>>
* <<breaking_50_percolator>>
* <<breaking_50_suggester>>
* <<breaking_50_index_apis>>
* <<breaking_50_document_api_changes>>
* <<breaking_50_settings_changes>>
* <<breaking_50_allocation>>
* <<breaking_50_http_changes>>
* <<breaking_50_rest_api_changes>>
* <<breaking_50_cat_api>>
* <<breaking_50_java_api_changes>>
* <<breaking_50_packaging>>
* <<breaking_50_plugins>>
* <<breaking_50_fs>>
* <<breaking_50_aggregations_changes>>
* <<breaking_50_scripting>>


include::migrate_5_0/search.asciidoc[]

include::migrate_5_0/mapping.asciidoc[]

include::migrate_5_0/percolator.asciidoc[]

include::migrate_5_0/suggest.asciidoc[]

include::migrate_5_0/index-apis.asciidoc[]

include::migrate_5_0/docs.asciidoc[]

include::migrate_5_0/settings.asciidoc[]

include::migrate_5_0/allocation.asciidoc[]

include::migrate_5_0/http.asciidoc[]

include::migrate_5_0/rest.asciidoc[]

include::migrate_5_0/cat.asciidoc[]

include::migrate_5_0/java.asciidoc[]

include::migrate_5_0/packaging.asciidoc[]

include::migrate_5_0/plugins.asciidoc[]

include::migrate_5_0/fs.asciidoc[]

include::migrate_5_0/aggregations.asciidoc[]

include::migrate_5_0/scripting.asciidoc[]