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 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)	Upgrading a Kubernetes deployment to 1.25.x from 1.24.x or lower.
1.30 (BlockMax WAND migration)	Moving collections created before 1.30 to the BlockMax WAND inverted index format.
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.
• 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.

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:
   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 creates a single named vector called default with the vectorizer set to none, instead of a single vector collection. DEFAULT_VECTORIZER_MODULE is not applied to it, so supply the vectors yourself for auto-created collections or add a vector after the collection is created.
• From v1.40, a collection definition that sets no vector parameters at all creates a collection without a 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. This requires a one-time migration of the cluster metadata.

In Docker-based self-hosted instances, the migration is automatic.

In Kubernetes-based self-hosted instances, you must perform a manual migration step. For more information, see the Weaviate v1.25.0 migration guide.

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.
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.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.