--- title: "Migration and Upgrades" description: "Upgrades" url: https://docs.weaviate.io/deploy/migration --- # Migration and Upgrades ## Upgrades Weaviate is under active development, with new features and improvements being added regularly, including bugfixes. To take advantage of these updates, we recommend upgrading your Weaviate instance regularly. ### General upgrade instructions When upgrading Weaviate, we recommend that you: 1. Create a complete [backup](https://docs.weaviate.io/deploy/configuration/backups) of your current Weaviate instance before beginning any upgrade process. 2. Plan to upgrade one minor version at a time, always using the latest patch version of each minor release. This approach of upgrading one minor version at a time helps to minimize the risk of issues during the upgrade process, by mirroring our testing and release process. Upgrading to the latest patch version of each minor release ensures that you have the latest bugfixes and improvements. ### Version-specific migration guides These guides cover upgrades that need steps beyond swapping the image: | Guide | Applies when | | - | - | | [1.25 (for Kubernetes users)](https://docs.weaviate.io/deploy/migration/weaviate-1-25) | Upgrading a Kubernetes deployment to `1.25.x` from `1.24.x` or lower. | | [1.30 (BlockMax WAND migration)](https://docs.weaviate.io/deploy/migration/weaviate-1-30) | Moving collections created before `1.30` to the BlockMax WAND inverted index format. | | [Archive](https://docs.weaviate.io/deploy/migration/archive) | Versions `1.19` and older. | Two further notes apply to versions without their own guide: - When upgrading to version `1.25.x` from `1.24.x` (or lower), you must perform a [Raft migration](https://docs.weaviate.io/deploy/migration#raft-migration-v1250). - When upgrading to version `1.26.x` or higher (from the preceding version), ensure that the cluster metadata is synchronized. - To do so, poll the `/cluster/statistics` endpoint, and check that the correct number of nodes are reporting statistics, and the `synchronized` flag is showing `true`, before proceeding with the upgrade. - For an example implementation, see the [`wait_for_raft_sync` function here](https://github.com/weaviate/weaviate-local-k8s/blob/main/utilities/helpers.sh). > [!TIP] > > **Scenario: upgrading from `v1.25.10` to `v1.27`** > > Between `v1.25` and `v1.27`, there are two minor versions, `v1.26` and `v1.27`. So: > > > > 1. Create a backup of your current Weaviate instance. > > 2. Go to the [Weaviate releases page](https://github.com/weaviate/weaviate/tags): > > 1. Find the latest `v1.26` patch version (e.g.: `1.26.11`). > 2. Find the latest `v1.27` patch version (e.g.: `1.27.5`). > > 3. Upgrade to the latest patch version of `v1.26`. > > 4. Upgrade to the latest patch version of `v1.27`. ### Vector configuration defaults (v1.39.1+, v1.40.0+) Three defaults for **new** collections changed. Existing collections are untouched, but if you rely on `DEFAULT_VECTORIZER_MODULE` you must act before upgrading to `v1.40`. - From `v1.39.1`, [auto-schema](https://docs.weaviate.io/weaviate/config-refs/collections#auto-schema) creates a single named vector called `default` with the vectorizer set to `none`, instead of a [single vector collection](https://docs.weaviate.io/weaviate/config-refs/collections#single-vector-collections). [`DEFAULT_VECTORIZER_MODULE`](https://docs.weaviate.io/deploy/configuration/env-vars#DEFAULT_VECTORIZER_MODULE) is not applied to it, so supply the vectors yourself for auto-created collections or [add a vector](https://docs.weaviate.io/weaviate/manage-collections/vector-config#add-new-named-vectors) after the collection is created. - From `v1.40`, a collection definition that sets no vector parameters at all creates a [collection without a vector](https://docs.weaviate.io/weaviate/config-refs/collections#no-vector). Previously the server defaults filled in the top-level parameters and created a single vector collection. From `v1.40`, the default top-level `vectorizer` is always `none`. It used to come from `DEFAULT_VECTORIZER_MODULE`, which is now deprecated and ignored. This is breaking if you relied on that variable. A definition that sets `vectorIndexType` or `vectorIndexConfig` but no `vectorizer` still creates a single vector collection, but it no longer vectorizes your data. Weaviate returns no error or warning. Before you upgrade, name the vectorizer explicitly in every collection definition that needs one. Older clients that always send `vectorIndexType` still create a single vector collection. ### Raft Migration (v1.25.0+) Weaviate `v1.25.0` introduced Raft [as the consensus algorithm for cluster metadata](https://docs.weaviate.io/weaviate/concepts/replication-architecture/cluster-architecture#metadata-replication-raft). This requires a one-time migration of the cluster metadata. In [Docker-based self-hosted instances](https://docs.weaviate.io/deploy/installation-guides/docker-installation), the migration is automatic. In [Kubernetes-based self-hosted instances](https://docs.weaviate.io/deploy/installation-guides/k8s-installation), you must perform a manual migration step. For more information, see the [Weaviate `v1.25.0` migration guide](https://docs.weaviate.io/deploy/migration/weaviate-1-25). This was a significant change to the Weaviate architecture. Accordingly, we suggest performing another backup after upgrading to `v1.25.latest`, before proceeding with further upgrades to ensure that you have a recent backup. ### Backup Restoration Fix (v1.23.13+) Before `v1.23.13`, there was a bug with the backup restoration process, which could lead to data not being stored correctly. If you are upgrading from a version before `v1.23.13`, we recommend that you: 1. Create a backup of your current Weaviate instance. 2. Upgrade to at least `v1.23.13` (preferably to `v1.23.16`) or higher, using the [general upgrade instructions above](https://docs.weaviate.io/deploy/migration#general-upgrade-instructions). 3. Restore your backup to the upgraded instance. ## Downgrades ### RAFT Snapshots (v1.28.13+, v1.29.5+, v1.30.2+) Multi-node instances of Weaviate running `1.28.13+`, `1.29.5+`, or `1.30.2+` may experience problems if downgraded to a `v1.27.x` version earlier than `1.27.26`. The cluster may not reach a **Ready** state due to a change in the way that RAFT snapshots are stored in the database. The fix shipped in `1.27.26`, which safely handles the downgrade path to `1.27`. If you need to downgrade Weaviate to `v1.27.x`, use `1.27.26` or higher.