Why the Dify Weaviate client v4 upgrade needs its own plan
If you run Dify with your own Weaviate server and you are moving to Dify 1.9.2 or later, the Weaviate server version must match the client change, and the path is a staged server upgrade rather than a single image swap. Dify 1.9.2 to 1.13.0 pairs weaviate-client v4.17.0 with Weaviate 1.27.0 or higher, while Dify 1.9.1 and earlier pairs v3 with Weaviate 1.19.0 to 1.26.x. If your Weaviate server is still in the 1.26 range, pulling the new Dify images first will leave the application unable to reach its vector store in the way it expects. Treat the Weaviate server as a separate workstream with its own backup, change window and verification steps, not as a side effect of the Dify upgrade.
Weaviate minor releases arrive on their own schedule, so the gap between your server and the target can grow quickly. Dify's own releases are also frequent: the GitHub releases page shows 1.16.0 on July 17, 2026, 1.17.0 on August 25, 2026 and 1.17.1 on September 10, 2026, so minor Dify releases are arriving roughly monthly. Confirm which Weaviate image your target Dify version bundles, and confirm the server version you run today with curl against the Weaviate meta endpoint before you schedule anything. Then read the Dify Weaviate migration guide for the compatibility matrix that applies to your starting and target versions, and plan each Weaviate minor step in order.
Weaviate Cloud customers are not affected by this change because Weaviate Cloud manages the server version. If you use a managed Weaviate instance, your work is limited to confirming the Dify version and client settings. If you operate the server yourself, whether through the bundled Compose service or your own cluster, the plan must cover the server ladder, the gRPC port change on 50051 that the v4 client uses by default, and a rollback point before each rung. Ask your team to name the owner for each Weaviate step and to confirm that the firewall rules and load balancers allow gRPC traffic before the cutover.
What changes in the Weaviate client and server
This table lists the changes that affect a self-hosted Dify with its own Weaviate, from the client move at Dify 1.9.2 to the bundled server version in Dify 1.17.1. Read each row against your current Dify and Weaviate versions to see which actions apply to your deployment.
| Change | Impact | Action needed |
|---|---|---|
| Move to weaviate-client v4 at Dify 1.9.2 | Dify 1.9.2 and later use the v4 client, so the client and server version pairing changes at this release. | Confirm your Dify version and the Weaviate server version before upgrading Dify. |
| Dify 1.9.1 and earlier with v3 | Pairs with Weaviate 1.19.0 to 1.26.x according to the compatibility matrix. | If you run an older Dify on these server versions, plan the server upgrade alongside the Dify upgrade. |
| Dify 1.9.2 to 1.13.0 with v4.17.0 | Requires Weaviate 1.27.0 or higher according to the compatibility matrix. | Check that your Weaviate server is at 1.27.0 or higher before running these Dify versions. |
| Default gRPC port 50051 | The v4 client uses gRPC by default on port 50051, so this port must be reachable from Dify. | Confirm the gRPC port is open between Dify containers and Weaviate, and check firewall and network policy rules. |
| Bundled Weaviate 1.39.2 in Dify 1.17.1 | The Weaviate image bundled with Dify 1.17.1 is 1.39.2, a long step from 1.27. | Step through Weaviate minor releases in order and verify data at each step rather than jumping directly. |
| Weaviate Cloud exception | Weaviate Cloud users are not affected because Weaviate Cloud manages the server version. | Confirm with your provider whether you run self-managed Weaviate, since the staged steps apply only to self-managed servers. |
What to check before touching the Weaviate server
Five checks come before any Weaviate server change, and each one protects a different part of the upgrade. Together they establish what is running today, what can be recovered, which configuration will break, and where the change is heading. Skipping any of them turns a routine step into a guessing exercise.
Confirm the running Weaviate version
Find out which Weaviate server version is actually running, not which version the compose file implies. Check the image tag in docker-compose.yaml and the live container, since a customized image or an older pinned tag can differ from the Dify default. The migration guide's compatibility matrix maps server versions to client versions, so this number decides which rung of the upgrade you start from.
Back up the Weaviate data volume
Stop and copy the Weaviate data volume before any server change, and keep the copy outside the host that runs Dify. Record the volume name, the backup location and a checksum or file listing so a restore can be verified. Confirm that a restore works in a scratch environment, because an untested backup gives no rollback path if a server step fails.
Inventory port 50051 and Weaviate host settings
Search your .env files, docker-compose.yaml overrides, firewall rules and any reverse proxy or network policy for the Weaviate host name, the HTTP port and port 50051. Version 4 of the client uses gRPC on that port by default, so a rule that allows only the HTTP port will block the new traffic. Record every custom setting so it can be reapplied after the Dify image changes.
Build a test environment with a data copy
Create a separate Dify and Weaviate stack that runs the same versions and a copy of the production vector data. Use it to rehearse each server step, to measure object counts and query results, and to test the gRPC path from the Dify containers. Keep it isolated from production users and from any model or outbound connections that could replay live traffic.
Confirm the current and target Dify versions
Record the Dify version in place and the version you plan to reach, then read the compatibility rows that span that range. Dify 1.9.2 to 1.13.0 pairs with the v4 client, and later releases bundle their own Weaviate image, so a jump past 1.13.0 changes the server target as well. Ask the team to confirm the target before any server step starts.
How to step the Weaviate server through minor releases
This sequence moves a self-hosted Weaviate server from its current minor version to the version Dify expects, one minor release at a time, with object counts and retrieval checked at each rung so any regression is caught while a rollback point still exists.
Confirm current server and Dify versions
The operator records the running Dify release, the Weaviate server version (for example, from the Weaviate container image tag or the server's meta endpoint) and the weaviate-client version pinned in the Dify api image. Compare these against the compatibility matrix in the Dify Weaviate migration guide. Dify 1.9.2 to 1.13.0 pairs with weaviate-client v4.17.0 and Weaviate 1.27.0 or higher, while Dify 1.9.1 and earlier pair with v3 and Weaviate 1.19.0 to 1.26.x. Done when the target Weaviate release is written down and the path from the current minor version to it is listed in order.
Back up the Weaviate data volume
Before any server change, the operator takes a backup of the Weaviate data volume and the Dify environment file, and records the object count for each collection that Dify uses. Confirm the backup can be restored into a scratch environment, not only that the copy completed. This backup is the first rollback point, and it should be kept until retrieval has been tested after the final rung. Done when a restore has been tested or the team has signed off on the restore method and its timing.
Stop api and worker services
The operator stops the Dify api and worker containers so no new documents are indexed or written to Weaviate during the server change. Other services can keep running if they do not write to the vector store. Confirm with a container status check that api and worker are down, and that no ingestion tasks are queued in Redis or the worker log. Done when writes to Weaviate have stopped, which keeps the object counts from each rung comparable.
Upgrade Weaviate one minor release at a time
The operator moves the Weaviate server to the next minor release, starting from the current version and never skipping a minor. Each rung uses the image or binary for that release, with the same data volume mounted and the same persistence settings. Weaviate's own upgrade notes for each release should be read before the change, because a server release can require a specific prior version. Done when the server reports the expected version and starts cleanly with its existing data loaded.
Verify object counts and search at each rung
After each minor release, the operator compares object counts per collection with the counts recorded before the upgrade, then runs a fixed set of test vector queries against known documents and saves the returned IDs. A count mismatch or changed results stops the sequence. The rollback point for this rung is the volume snapshot taken before the rung started, so the operator can restore the previous minor version and its data. Done when counts match and the test queries return the expected documents.
Update Dify version and client settings
The operator moves the Dify deployment to the release in the compatibility matrix, then checks that the Weaviate client version bundled with that release matches the matrix entry. Settings in the environment file are reviewed against the current .env.example, including the Weaviate host, the gRPC settings and the API key if one is enabled. Done when the Dify api image and environment file are updated, and the team has confirmed the client version against the matrix. Confirm the exact variable names in the release notes for the chosen Dify version.
Check the gRPC port on both sides
The client v4 uses gRPC by default on port 50051, so the operator confirms that the Weaviate server exposes the gRPC port on the network the Dify api and worker use, and that the Dify configuration points to that port. Container port mappings, firewall rules and any reverse proxy in front of Weaviate are checked, because a server listening only on the HTTP port will fail on the first query. Done when a connection test from the Dify api container reaches both the HTTP and gRPC ports.
Restart services and test retrieval
The operator starts the api and worker containers, then runs a knowledge base retrieval test and a document indexing test on a non-production dataset. Object counts are checked once more and a small document is ingested and retrieved end to end. Logs from api and worker are reviewed for client errors. Done when retrieval returns expected results and ingestion completes. If either fails, the operator uses the backup and the last working rung to roll back before the change is released to users.
How the gRPC port change affects Dify networking
The weaviate-client v4 library opens a gRPC connection on port 50051 by default, in addition to the HTTP port that earlier client versions used. Any firewall rule, security group, Compose network setting, reverse proxy route or Kubernetes network policy that only allows the HTTP port will let Dify's health-style checks pass in some paths while vector reads and writes from the api and worker containers fail. Before you change the Dify version, add the gRPC port to the path between those containers and your Weaviate server, and record the rule in your change ticket so it survives the next network review.
To confirm reachability, run a test from inside the api and worker containers, not from your workstation or a jump host, because container networks often differ from host networks. Use the container runtime's exec command to open a shell in each service, then test the Weaviate host on the HTTP port and on port 50051 with a basic TCP tool available in the image. Then run a read or write through the Dify knowledge base after the upgrade, since a successful TCP handshake does not prove the gRPC session works. Confirm the port mapping in your compose file or Helm values against the Weaviate and Dify documentation for your versions.
The bundled Compose setup and a custom Weaviate deployment differ in ways that matter here. With the bundled service, the port is reachable on the internal Compose network by service name, so the main risk is a locally added port restriction. With an external Weaviate, check the load balancer or ingress, which often forwards only HTTP, and ask your network team whether gRPC traffic is inspected, rate-limited or blocked by TLS termination rules. Confirm with the Weaviate and Dify migration guide whether your Weaviate deployment needs any further port or TLS settings, and do not assume a default you have not verified.
What makes the Weaviate upgrade longer
This table compares the conditions that lengthen the Weaviate step of a Dify upgrade and the effect each has on effort. Read each row as a question to answer about your own deployment before you request a quote. The main takeaway is that the version distance from your current Weaviate server to the target is the largest single driver, and it is usually the one teams have checked least.
| Driver | Effect on effort | What to confirm |
|---|---|---|
| Current Weaviate version distance | Each minor server release between your version and the target is a separate step to back up, start and verify, so a deployment still on 1.27 has the longest path | Exact Weaviate server version in your running container and the minor releases between it and the bundled target in the Dify migration guide |
| Data volume and reindex time | Larger collections take longer to stop, snapshot and restart, and any reindexing or re-embedding after the client change extends the window | Object counts per knowledge base collection and how long a test restore and reindex took in a non-production copy |
| Custom Compose or Kubernetes networking | Changing the client to gRPC on port 50051 means firewall rules, network policies, service definitions and health checks may need edits in addition to image changes | Whether the api and worker containers can reach the Weaviate gRPC port, and which manifests or override files you have customized |
| Number of Dify environments | Development, staging and production each need the same staged server path, so effort multiplies unless one environment is used as the rehearsal for the rest | Which environments hold live Weaviate data, and whether they share a server or a snapshot pipeline |
| Self-managed versus Weaviate Cloud | Self-managed servers require you to plan the server stepping and verification yourself, while Weaviate Cloud manages the server version, which removes that work | Who operates the Weaviate server and whether any instance is hosted under a Weaviate Cloud arrangement |
| Availability needs for retrieval during the window | If knowledge base retrieval must stay up, the window needs a planned maintenance period, a rollback path and possibly a second environment to test cutover | Acceptable retrieval downtime for your users and applications, and who approves the maintenance window |
Questions buyers ask about the Weaviate upgrade
What does a Weaviate client v4 upgrade cost and what drives the price?
The price follows from the written scope, not from a fixed rate. The main drivers are how many Dify environments share the Weaviate server, how many minor Weaviate releases sit between your current server and the target, how much data and how many collections must be verified after each step, and whether the Dify instance is customized in ways that affect the upgrade. Some work is one-time (assessment, the staged upgrade, verification, runbook), while follow-on work such as a later Dify or Weaviate upgrade may recur if you buy a support retainer. Ask for a quote that lists each environment, each Weaviate step, the backup and rollback approach, and who performs the verification. DeployOpen does not publish a price list.
How long does the Weaviate upgrade take?
Duration depends mainly on how many minor Weaviate releases you must step through, the size of the vector data, and how much maintenance window your users can accept. Each step needs a backup, a restart and a check that object counts and queries still match before moving on, so the number of steps is the main variable. Dify's guidance requires stepping through the Weaviate minor releases in order rather than jumping straight to the target. Ask the provider to state the number of steps, the window needed per step, and the conditions that would pause the work, such as a failed count check.
Can our internal team do the Weaviate upgrade without a partner?
Yes, if your team has Docker Compose experience, can read the Dify compatibility matrix and has someone who can run a restore test. The work is procedural: confirm the Dify and Weaviate versions, pin the weaviate-client v4 release that matches your Dify version, step the server through each minor release in order, and change the gRPC port setting to 50051 where needed. The risk is in skipping the backup or the object-count checks between steps. A partner adds value when the environment is shared, customized, or hard to roll back, or when you want the evidence recorded for an audit.
What do you need from us to start the upgrade?
Expect to provide the following before work starts:
- Read access to the Compose project, the
.envfile and any customizeddocker-compose.yamlchanges - Access to the host running Dify and Weaviate, plus a copy or snapshot of the Weaviate data volume
- A maintenance window agreed with the business owners of the Dify apps and knowledge bases
- Records of the current Dify version, the current Weaviate server version and the client version in use
- Named contacts for sign-off on verification results
Without the version records, the first task becomes establishing them, which lengthens the assessment phase.
Do Weaviate Cloud users need to change anything?
Generally no for the server side. Dify's Weaviate migration guide states that Weaviate Cloud users are not affected because Weaviate Cloud manages the server version. Confirm this against your own setup: if you use Weaviate Cloud, check that your Dify version is still compatible with the cloud endpoint and API key configuration, and check the Dify release notes for any client change. Self-hosted Weaviate servers are the cases that need the staged server upgrade.
Which Dify versions need the Weaviate client change?
The compatibility matrix in the Dify Weaviate migration guide places Dify 1.9.1 and earlier with weaviate-client v3 for Weaviate 1.19.0 to 1.26.x, and Dify 1.9.2 to 1.13.0 with v4.17.0 for Weaviate 1.27.0 or higher. Check the matrix against your exact Dify and Weaviate versions before choosing a path, because a mismatch between the server and client is the most common reason the upgrade fails.
What breaks if the gRPC port or server version is wrong?
A mismatched client and server usually show up as failed connections or errors on knowledge base queries, not as a clean startup failure, so verify retrieval after the upgrade rather than only checking that containers are running. weaviate-client v4 uses gRPC on port 50051 by default, so a firewall rule, Compose port mapping or network policy that only allows the older HTTP path can block it. Confirm that the port is reachable between the Dify api and worker containers and the Weaviate service.
How to test retrieval and roll back safely
Treat every Weaviate minor release as a checkpoint that must pass before the next one starts. After each rung, confirm that the server reports the expected version, that object counts in each Dify knowledge base match the counts recorded before the upgrade step, and that the Dify API and worker containers are healthy. Object counts catch silent data loss, but they do not prove retrieval works, so the second check is a fixed set of sample queries run against a knowledge base whose expected answers you wrote down before starting. Use the same questions at every rung and record which source documents each one returns.
Finish each rung by indexing one new test document into a non-production knowledge base and confirming it becomes retrievable through the same query set. This exercises the write path that the weaviate-client v4 change affects, which read-only checks miss. Confirm the gRPC port change at this stage as well, since a reachable HTTP endpoint with a broken gRPC path can look healthy until indexing fails. If any check fails, stop, do not advance the server, and do not run further database migrations.
Before each rung, stop the api and worker services and back up the Weaviate volume, so that the rollback point is a copy taken while the data is at rest. To roll back, stop the containers, restore that volume backup, and pin the previous Weaviate image tag, the Dify version and the matching client version from the compatibility matrix in the Dify Weaviate migration guide. Restoring the server alone is not enough, because the Dify version determines which client talks to it. Record for every rung the Weaviate and Dify versions, object counts, query results, the backup location and the operator who signed off, so the next rung starts from a known, written state.
How DeployOpen scopes and delivers the Weaviate client upgrade
DeployOpen plans the Weaviate client change as a fixed-scope piece of work inside your own infrastructure, starting from the Weaviate server version you actually run. We sequence the minor server releases, the gRPC port change and the Dify version jump so each step can be checked before the next one starts.
How we scope
- Confirm your current Dify version, Weaviate server version and whether Weaviate is bundled or external.
- Write down the target Dify version and the Weaviate minor releases needed to reach it in order.
- Agree in writing which network paths, firewall rules and gRPC port 50051 changes your environment requires.
How we build
- Back up the Weaviate data volume and Dify configuration before any change touches the running stack.
- Step the Weaviate server through each minor release, recording object counts and health checks at every rung.
- Update the Dify deployment and client configuration, then test queries against a knowledge base after each change.
How we hand over
- Deliver a written runbook covering the exact version sequence, backup points, rollback steps and verification results.
- Document the compatibility matrix entries that apply to your Dify and Weaviate versions for your change records.
- Walk your platform and security teams through the operating checks you will run after each future upgrade.
How we support
- Available as an ongoing retainer for upgrades, patch reviews and continuous checks after each Dify minor release.
- Review release notes and the Weaviate migration guide again before any later Dify or Weaviate version change.
- Agree support scope, response expectations and upgrade cadence in writing before the retainer begins.
