# 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](../storage-and-backups/backups.md) 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

- When upgrading to version `1.25.x` from `1.24.x` (or lower), you must perform a [Raft 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).

:::callout{intent="tip" title="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`.
:::

### Raft Migration (v1.25.0+)

Weaviate `v1.25.0` introduced Raft [as the consensus algorithm for cluster metadata](../replication-architecture/cluster-architecture.md#metadata-replication-raft). This requires a one-time migration of the cluster metadata.

In [Docker-based self-hosted instances](../installation/installation-guides-docker-installation.md), the migration is automatic.

In [Kubernetes-based self-hosted instances](../installation/installation-guides-k8s-installation.md), you must perform a manual migration step. For more information, see the [Weaviate `v1.25.0` migration guide](../deploy-migration/weaviate-1-25.md).

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](#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.

A fix for this issue will be released with `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.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.