docs: add weaviate server upgrade path guide - #940
Merged
Ill-donut merged 12 commits intoSep 10, 2026
Merged
Conversation
dosubot
Bot
added
size:XL
4 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new troubleshooting guide documenting the supported “one minor at a time” upgrade ladder for self-hosted Weaviate server deployments, bridging the gap from the previously documented 1.27-era guidance to Dify’s newer bundled Weaviate (1.39.0). It also cross-links this new guide from the existing Weaviate v4 migration guide and updates navigation across all three languages.
Changes:
- Adds a new “Weaviate Server Upgrade Path” page in
en/, pluszh/andja/translations. - Cross-links the existing Weaviate v4 migration guide to route 1.27+ users to the new server upgrade ladder.
- Updates
docs.jsonnavigation for en/zh/ja troubleshooting sections to include the new page.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx | Adds an Info callout linking to the new server upgrade path guide. |
| en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx | New English guide describing the minor-by-minor upgrade ladder and operational pitfalls. |
| zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx | Adds an Info callout linking to the new server upgrade path guide (zh). |
| zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx | New Chinese translation of the server upgrade path guide. |
| ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx | Adds an Info callout linking to the new server upgrade path guide (ja). |
| ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx | New Japanese translation of the server upgrade path guide. |
| docs.json | Adds the new page to the Troubleshooting nav for en/zh/ja. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
dudanogueira
added a commit
to dudanogueira/dify-docs
that referenced
this pull request
Aug 12, 2026
Review feedback on langgenius#940: - The warning said "twelve-step ladder" and the blast-radius note said "twelve-version jump" while the table lists thirteen rungs. Both counts are now phrased so they stay correct if the ladder changes. - zh used 回合到 for backporting, which does not read as Chinese. Rewritten as 合入. Applied to ja as well, where the same counts appeared as 10 段階 and 10 以上のバージョン.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
Suppressed comments (11)
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:58
- This sentence refers to “bisecting a twelve-version jump”, but the exact number of rungs here is not 12 (the table includes a 1.27 patch step plus minors). Consider removing the hard-coded count to keep the wording accurate as the ladder changes.
Stepping one minor at a time also limits your blast radius. When a rung misbehaves, you roll back a single version and know exactly which release caused it, instead of bisecting a jump that crossed every minor at once.
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:57
- The compatibility matrix uses
v4.20.x, but Dify pins exact patch versions, and the PR description notes a patch-level change between 1.13.1 and 1.14.0+. Usingxmakes the table less precise than the surrounding rows (e.g.,v4.17.0) and can mislead source installs trying to match the pinned client.
| Dify Version | Weaviate-client Version | Compatible Weaviate Server Versions |
| -------------- | ----------------------- | ----------------------------------- |
| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x |
| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 or higher |
| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 or higher |
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:14
- In this warning, the text says “twelve-step ladder”, but the ladder below lists steps 0–13 (and may vary depending on a user's start version). Using a fixed number will become inaccurate as the table changes.
This issue also appears on line 58 of the same file.
<Warning>
Back up your Weaviate volume before you start. An upgrade that goes wrong partway through the ladder is only recoverable if you have a snapshot to return to.
</Warning>
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:163
- The phrase “Version
4.22.0, which current Dify ships” is ambiguous (and conflicts with the earlier matrix that stops at 1.16.x). To avoid going stale or implying a tagged release pin, it’s clearer to refer to “the version pinned by your Dify checkout” instead of a specific version number.
The Python `weaviate-client` also needs no attention. Version `4.22.0`, which current Dify ships, works against every server version on the ladder, so you can upgrade the server independently.
zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:59
- 兼容性矩阵里用
v4.20.x会掩盖 Dify 实际固定的是具体补丁版本（且 1.13.1 与 1.14.0+ 的补丁版本不同）。表格其它行使用了精确版本号（如v4.17.0），建议这里也写到补丁级别以便源码安装对齐依赖。
| Dify 版本 | Weaviate-client 版本 | 兼容的 Weaviate 服务器版本 |
| ------------ | ----------------------- | ----------------------------------- |
| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x |
| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 或更高版本 |
| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 或更高版本 |
ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:59
- 互換性マトリックスが
v4.20.xになっていますが、Dify は実際にはパッチまで固定しており（1.13.1 と 1.14.0+ でパッチが異なる）、他の行（例:v4.17.0）は厳密な表記です。ソースインストールで依存を合わせやすいよう、ここもパッチまで明記した方が正確です。
| Dify バージョン | Weaviate-client バージョン | 互換性のある Weaviate サーバーバージョン |
| ------------ | ----------------------- | ----------------------------------- |
| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x |
| 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 以降 |
| 1.13.1 - 1.16.x | v4.20.x | 1.27.0 以降 |
zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:165
- “当前 Dify 附带的
4.22.0” 这一表述容易过期，也可能被理解为“已发布版本”固定了该版本。为避免与前文兼容矩阵（截至 1.16.x）产生歧义，建议改为“使用当前 Dify 代码固定的版本”。
Python `weaviate-client` 同样无需处理。当前 Dify 附带的 `4.22.0` 可与阶梯上的所有服务器版本配合工作，因此服务器可以单独升级。
ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:165
- 「現行の Dify が同梱する
4.22.0」は将来すぐに古くなる表現で、タグ付きリリースがそのバージョンを固定しているかのように読めてしまいます。前ページの互換表（〜1.16.x）とも整合しづらいので、「チェックアウトが固定しているバージョン」を参照する表現にすると誤解を減らせます。
Python の `weaviate-client` についても対応は不要です。現行の Dify が同梱する `4.22.0` は一覧のすべてのサーバーバージョンで動作するため、サーバーだけを個別にアップグレードできます。
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:636
- The troubleshooting snippet runs Docker Compose and then
uv sync --project apiin the same code block, but it doesn't clarify the working directory. If a reader is indocker/for the Compose commands (as elsewhere in this guide),--project apiwill resolve todocker/apiand fail. Make the directory context explicit so copy/paste works.
docker compose down
docker compose up -d
# For source installations, install the version your Dify checkout pins
uv sync --project api --group vdb-weaviate
zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:637
- 这段排障命令同时包含 Docker Compose 和
uv sync --project api，但没有说明工作目录。如果读者按常见做法在docker/下运行 Compose，--project api会解析为docker/api并失败。建议把目录切换写清楚，确保复制粘贴即可执行。
docker compose down
docker compose up -d
# 对于源码安装，安装当前 Dify 代码固定的版本
uv sync --project api --group vdb-weaviate
ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:637
- このコードブロックは Docker Compose と
uv sync --project apiを並べていますが、実行ディレクトリが明示されていません。ガイド内の他箇所と同様にdocker/で Compose を実行した場合、--project apiがdocker/apiを指して失敗します。ディレクトリ移動を明記してコピペで動くようにすると安全です。
docker compose down
docker compose up -d
# ソースインストールの場合、Dify のコードが固定しているバージョンをインストールします
uv sync --project api --group vdb-weaviate
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
Suppressed comments (9)
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:126
- The verification block also uses the redacted
Authorization: ******placeholder without stating what it represents. Add a one-line hint after definingKEYso users know to replace******withBearer $KEY.
KEY="<WEAVIATE_API_KEY>"
zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:128
- 这里定义了
KEY，但下面的 header 仍是Authorization: ******，且未解释其含义。建议在KEY后补充一行注释，提示把******替换为Bearer $KEY。
KEY="<WEAVIATE_API_KEY>"
ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:128
KEYを定義していますが、下のヘッダーはAuthorization: ******のままで、何を入れるべきかが明記されていません。******をBearer $KEYに置き換える注釈を 1 行追加してください。
KEY="<WEAVIATE_API_KEY>"
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:636
uv sync --project api --group vdb-weaviatedepends on running from the Dify repo root (soapi/resolves). Add an explicitcd /path/to/dify(or similar) so readers don’t run this from the wrong directory.
# For source installations, install the version your Dify checkout pins
uv sync --project api --group vdb-weaviate
zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:637
uv sync --project api --group vdb-weaviate需要在 Dify 仓库根目录执行（否则找不到相对路径api/）。建议在命令前明确cd /path/to/dify，避免读者在错误目录下运行导致失败。
# 对于源码安装，安装当前 Dify 代码固定的版本
uv sync --project api --group vdb-weaviate
ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:637
uv sync --project api --group vdb-weaviateは Dify リポジトリのルートから実行しないと（相対パスのapi/が解決できず）失敗します。実行ディレクトリを明示するcd /path/to/difyを追加してください。
# ソースインストールの場合、Dify のコードが固定しているバージョンをインストールします
uv sync --project api --group vdb-weaviate
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:19
- The curl snippets use a redacted
Authorization: ******value, but don’t explain what it should be replaced with. Add an explicit note inside the code block so readers know to supply aBearer <WEAVIATE_API_KEY>value.
This issue also appears on line 125 of the same file.
```bash
curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
zh/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:21
- 代码块里使用了脱敏后的
Authorization: ******，但没有说明******需要替换成什么。建议在命令前加一行注释，明确应填Bearer <WEAVIATE_API_KEY>，避免读者照抄失败。
This issue also appears on line 127 of the same file.
```bash
curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
ja/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:21
- コードブロック内の
Authorization: ******が伏せ字のままなので、何に置き換えるべきかが分かりません。Bearer <WEAVIATE_API_KEY>を入れる旨の注釈を 1 行追加して、コピペで迷わないようにしてください。
This issue also appears on line 127 of the same file.
```bash
curl -s -H "Authorization: Bearer <WEAVIATE_API_KEY>" \
crazywoola
previously approved these changes
Sep 3, 2026
Contributor
|
Thanks again for this contribution — the ladder approach and the compatibility-matrix corrections address a real documentation gap. We did a second verification pass against the current Dify codebase and Weaviate source/docs, and I’ll post the findings below as separate comments so they can be tracked independently. Could you handle the English/source-content changes? Once the content is settled, we can help with the zh/ja alignment and with rebasing the branch onto the latest |
Ill-donut
reviewed
Sep 3, 2026
Ill-donut
left a comment
Ill-donut
left a comment
Contributor
There was a problem hiding this comment.
Reposting the review findings as inline threads so each item can be resolved independently. Please handle the English/source-content changes; once those are settled, we can help align the zh/ja versions and rebase the branch onto the latest main.
| <Step title="Stop the Container Gracefully"> | ||
| ```bash | ||
| cd docker | ||
| docker compose stop weaviate |
Contributor
There was a problem hiding this comment.
4/13 — Apply the explicit graceful-stop timeout consistently
The page later recommends docker compose stop -t 120 weaviate, but the backup block, this main upgrade step, the middleware variant, and the rollback block all use plain docker compose stop weaviate.
Please use an explicit timeout consistently in all of those operational steps so the copied commands do not trigger the forced termination the guide warns about.
Contributor
Author
There was a problem hiding this comment.
Fixed in b8d73b1. docker compose stop -t 120 weaviate is now used in all four places: the backup block, the main upgrade step, the middleware variant and the rollback block.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
It introduces a broken verification command (GraphQL count parsing) and includes version statements that conflict with the PR’s own “not in tagged release yet” constraint.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 7/7 changed files
- Comments generated: 9
- Review effort level: Lite
| --header="Content-Type: application/json" \ | ||
| --post-data="{\"query\":\"{ Aggregate { $COLLECTION { meta { count } } } }\"}" \ | ||
| http://localhost:8080/v1/graphql \ | ||
| | python3 -c "import sys, json; print('count', json.load(sys.stdin)['data']['Aggregate']['$COLLECTION'][0]['meta']['count'])" |
|
|
||
| Your collections keep their existing layout, so no re-indexing is required and your knowledge bases keep working as they are. Dify stores each dataset as a `Vector_index_<dataset_id>_Node` collection with a self-provided named vector `default`. Dify does not set a distance metric, so the collection uses the server default of cosine. That structure is identical before and after the upgrade. | ||
|
|
||
| The Python `weaviate-client` also needs no attention. Use the version your Dify release pins: `4.20.5` for Dify 1.14.0 through 1.16.1, and `4.22.0` for 1.17.0. Both work against every server version on the ladder, so you can upgrade the server independently of Dify. |
| | 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 or higher | | ||
| | 1.13.1 - 1.13.3 | v4.20.4 | 1.27.0 or higher | | ||
| | 1.14.0 - 1.16.1 | v4.20.5 | 1.27.0 or higher | | ||
| | 1.17.0 | v4.22.0 | 1.27.0 or higher | |
| --header="Content-Type: application/json" \ | ||
| --post-data="{\"query\":\"{ Aggregate { $COLLECTION { meta { count } } } }\"}" \ | ||
| http://localhost:8080/v1/graphql \ | ||
| | python3 -c "import sys, json; print('count', json.load(sys.stdin)['data']['Aggregate']['$COLLECTION'][0]['meta']['count'])" |
|
|
||
| コレクションの構成は変わらないため、再インデックスは不要で、ナレッジベースもそのまま使えます。Dify は各データセットを `Vector_index_<dataset_id>_Node` コレクションとして保存し、自前で指定する名前付きベクトル `default` を使います。Dify は距離指標を設定しないため、コレクションはサーバー既定のコサイン距離になります。この構造はアップグレードの前後で同一です。 | ||
|
|
||
| Python の `weaviate-client` についても対応は不要です。利用中の Dify リリースが固定しているバージョンを使ってください。Dify 1.14.0 から 1.16.1 は `4.20.5`、1.17.0 は `4.22.0` です。どちらも一覧のすべてのサーバーバージョンで動作するため、サーバーだけを Dify と切り離してアップグレードできます。 |
| | 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 以降 | | ||
| | 1.13.1 - 1.13.3 | v4.20.4 | 1.27.0 以降 | | ||
| | 1.14.0 - 1.16.1 | v4.20.5 | 1.27.0 以降 | | ||
| | 1.17.0 | v4.22.0 | 1.27.0 以降 | |
| --header="Content-Type: application/json" \ | ||
| --post-data="{\"query\":\"{ Aggregate { $COLLECTION { meta { count } } } }\"}" \ | ||
| http://localhost:8080/v1/graphql \ | ||
| | python3 -c "import sys, json; print('count', json.load(sys.stdin)['data']['Aggregate']['$COLLECTION'][0]['meta']['count'])" |
|
|
||
| 集合结构保持原样，因此无需重建索引，知识库照常可用。Dify 把每个数据集存为 `Vector_index_<dataset_id>_Node` 集合，并使用自带命名向量 `default`。Dify 不设置距离度量，因此集合采用服务器默认的余弦距离。该结构在升级前后完全一致。 | ||
|
|
||
| Python `weaviate-client` 同样无需处理。使用你所用 Dify 版本固定的客户端版本即可：Dify 1.14.0 至 1.16.1 为 `4.20.5`，1.17.0 为 `4.22.0`。两者都能与阶梯上的所有服务器版本配合工作，因此服务器可以独立于 Dify 单独升级。 |
| | 1.9.2 - 1.13.0 | v4.17.0 | 1.27.0 或更高版本 | | ||
| | 1.13.1 - 1.13.3 | v4.20.4 | 1.27.0 或更高版本 | | ||
| | 1.14.0 - 1.16.1 | v4.20.5 | 1.27.0 或更高版本 | | ||
| | 1.17.0 | v4.22.0 | 1.27.0 或更高版本 | |
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
The updated compatibility matrix tables don’t follow the repo’s required table alignment format, and there is an unresolved mismatch between the PR description and the newly added v4.22.0 compatibility rows.
Review details
Suppressed comments (6)
Previously missed (3) — in code that hasn't changed since the last review.
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:54
- The formatting guide asks tables to be left-aligned by default using
:---in the separator row. This compatibility matrix currently uses plain dashes, so it won’t follow the repo’s standard table formatting.
ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:56 - The formatting guide asks tables to be left-aligned by default using
:---in the separator row. This compatibility matrix currently uses plain dashes, so it won’t follow the repo’s standard table formatting.
zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:56 - The formatting guide asks tables to be left-aligned by default using
:---in the separator row. This compatibility matrix currently uses plain dashes, so it won’t follow the repo’s standard table formatting.
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:59
- PR description says
weaviate-client 4.22.0is not in a tagged release yet and is deliberately not included in the matrix, but this table now includes a1.17.0 → v4.22.0row. Please align the docs with the intended policy (either remove/footnote the row, or update the PR description and clearly mark whether it’s released).
| 1.17.0 | v4.22.0 | 1.27.0 or higher |
zh/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:61
- PR description says
weaviate-client 4.22.0is not in a tagged release yet and is deliberately not included in the matrix, but this table now includes a1.17.0 → v4.22.0row. Please align the docs with the intended policy (either remove/footnote the row, or update the PR description and clearly mark whether it’s released).
| 1.17.0 | v4.22.0 | 1.27.0 或更高版本 |
ja/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:61
- PR description says
weaviate-client 4.22.0is not in a tagged release yet and is deliberately not included in the matrix, but this table now includes a1.17.0 → v4.22.0row. Please align the docs with the intended policy (either remove/footnote the row, or update the PR description and clearly mark whether it’s released).
| 1.17.0 | v4.22.0 | 1.27.0 以降 |
- Files reviewed: 7/7 changed files
- Comments generated: 0 new
- Review effort level: Lite
dudanogueira
added a commit
to dudanogueira/dify-docs
that referenced
this pull request
Sep 8, 2026
Per review feedback on langgenius#940, the maintainers will handle the zh/ja alignment once the English content is settled. Drop the zh/ja copies of weaviate-server-migration-path, revert the zh/ja weaviate-v4-migration edits to main, and remove the matching zh/ja navigation entries so no section points at a missing page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new page and updated guidance are not mirrored into the zh/ja locales (and corresponding nav sections), which breaks the repo’s expected en/zh/ja doc-sync workflow.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (1)
en/self-host/deploy/troubleshooting/weaviate-v4-migration.mdx:55
- The English Weaviate v4 migration page now has an updated compatibility matrix and new cross-link to the server upgrade ladder, but the zh/ja copies of this page still show the old matrix (including the “tested up to 1.33.1” note) and don’t link to the new page. Please mirror these content changes into the zh/ja versions to keep the three locales in sync.
## Version Compatibility Matrix
| Dify Version | Weaviate-client Version | Compatible Weaviate Server Versions |
|:---------------|:------------------------|:------------------------------------|
| ≤ 1.9.1 | v3.x | 1.19.0 - 1.26.x |
- Files reviewed: 3/3 changed files
- Comments generated: 2
- Review effort level: Lite
Comment on lines
736
to
+740
| "en/self-host/deploy/troubleshooting/docker-issues", | ||
| "en/self-host/deploy/troubleshooting/integrations", | ||
| "en/self-host/deploy/troubleshooting/storage-and-migration", | ||
| "en/self-host/deploy/troubleshooting/weaviate-v4-migration" | ||
| "en/self-host/deploy/troubleshooting/weaviate-v4-migration", | ||
| "en/self-host/deploy/troubleshooting/weaviate-server-migration-path" |
The existing v4 migration guide stops at server 1.27, but Dify now bundles 1.39 (langgenius/dify#38214). Existing deployments cannot jump that gap in one step: Weaviate does not test or support skipping minor versions. Adds a sibling page with the one-minor-at-a-time ladder and the two operational details that decide whether vectors survive it — graceful shutdown, which a hard kill silently costs you in HNSW recall, and the post-restart index-mount race. Cross-links both directions with the v4 page. en, zh and ja, with nav mirrored across all three sections.
The matrix listed v4.17.0 for every release from 1.9.2 onward and capped server coverage at "tested up to 1.33.1". Both are stale: the client moved to 4.20.4 in 1.13.1 and 4.20.5 in 1.14.0, and the server bound was a moving target that went out of date rather than a real limit. Splits the client rows at their actual boundaries, replaces the tested-up-to note with the reason the server column has no upper bound, and points readers at the server upgrade path for external instances. Also replaces the hardcoded `pip install weaviate-client==4.17.0` fix with `uv sync`, so source installs get whatever version their checkout pins instead of being pinned to a version Dify stopped shipping.
Review feedback on langgenius#940: - The warning said "twelve-step ladder" and the blast-radius note said "twelve-version jump" while the table lists thirteen rungs. Both counts are now phrased so they stay correct if the ladder changes. - zh used 回合到 for backporting, which does not read as Chinese. Rewritten as 合入. Applied to ja as well, where the same counts appeared as 10 段階 and 10 以上のバージョン.
Re-validated the ladder end to end before rewriting: a volume seeded on 1.27.0 was walked through all 13 rungs, verified at each with both weaviate-client 4.20.5 and 4.22.0 (28/28 runs passed on object count, byte-exact vectors, near_vector recall, BM25 and a write round-trip). Sequencing: the page no longer claims the image bump has happened. langgenius/dify#38214 is still open and 1.17.0 still pins semitechnologies/weaviate:1.27.0, so the opening now describes a pin that is moving and reads correctly before and after that PR lands. Corrections from the re-run: - Object count used /v1/objects?limit=1 and read totalResults, which is the page length, not the collection total (always 1). Replaced with a GraphQL Aggregate query. - Every curl targeted localhost:8080, which the default compose file does not publish. All checks now run through docker compose exec against the container, using busybox wget since the image has no curl or python. - The hard-kill section claimed the index "recovers once rebuilt". It does not. A kill left 20 of 700 objects in the store but off the HNSW graph, and they stayed missing across three restarts and a rewrite, with nothing logged. Rewritten with the measured numbers and the real remedy. - The mount-race error text was wrong: no restart produced "non-existing index". The window returns 404 and a GraphQL "no schema is present", and it grows from under 0.3s to 4-9s at 1.31. Replaced with measurements. - Tail rungs moved to 1.37.15 and 1.38.13; the final rung stays at Dify's pin rather than the newest patch, so the ladder cannot overshoot it. - Weaviate supports three minor versions in total, not four. - docker compose stop -t 120 is now used in all four operational blocks, and sudo cp -a replaces cp -r in backup and rollback. - Client guidance points at the version each Dify release pins. - Pre-1.27 readers are routed to the v4 guide by version, not "1.19". - Dify does not set a distance metric; cosine is the server default. - Registry change to cr.weaviate.io is now explained at the ladder. Compatibility matrix restored to patch precision, corrected against the dependency history: 4.20.4 spans 1.13.1-1.13.3, 4.20.5 spans 1.14.0-1.16.1, and 1.17.0 ships 4.22.0. The uv sync block is split out with an explicit cd to the repo root, since it fails if copied from docker/. zh and ja mirrored in the same pass; zh description switched from 自托管 to the glossary's 自部署. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD
langgenius/dify#38214 now pins 1.39.2, so the ladder's last rung follows it. The rung must match the pin exactly: landing the volume on a different patch and then applying the compose file is the downgrade the page warns about. Validated the changed step rather than assuming it. Restored the volume snapshot taken after 1.38.13 and stepped it to 1.39.2: all checks pass with both weaviate-client 4.20.5 and 4.22.0, the index-mount gap is 7.8s (inside the documented 4-9s band), and totalResults behaves as documented (1 at limit=1, 200 at limit=250). Re-ran the hard-kill experiment on 1.39.2 too, which reproduces the same 20-of-700 unreachable objects with no recovery across restarts, so the measured figures now cite one version throughout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD
Matches the separator style already used by the tables in weaviate-server-migration-path.mdx. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm
Per review feedback on langgenius#940, the maintainers will handle the zh/ja alignment once the English content is settled. Drop the zh/ja copies of weaviate-server-migration-path, revert the zh/ja weaviate-v4-migration edits to main, and remove the matching zh/ja navigation entries so no section points at a missing page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
It introduces a broken verification command in the new guide and adds a new page to navigation without mirroring the nav/translation updates for zh/ja in the same PR.
Review details
Suppressed comments (2)
docs.json:740
- This PR adds a new troubleshooting page to the English navigation, but the corresponding
zh/andja/docs.json sections are not updated (and the translated MDX pages are missing). Per repo docs conventions, navigation / structural changes need to be mirrored across all three languages in the same PR.
"en/self-host/deploy/troubleshooting/weaviate-v4-migration",
"en/self-host/deploy/troubleshooting/weaviate-server-migration-path"
en/self-host/deploy/troubleshooting/weaviate-server-migration-path.mdx:191
- The
Aggregatecount command indexes the JSON response with the literal key'$COLLECTION', so it will fail with a KeyError instead of using the collection name you set in theCOLLECTION=...variable. Use the shell-providedCOLLECTIONvalue inside the Python snippet.
| python3 -c "import sys, json; print('count', json.load(sys.stdin)['data']['Aggregate']['$COLLECTION'][0]['meta']['count'])"
- Files reviewed: 3/3 changed files
- Comments generated: 0 new
- Review effort level: Lite
Revalidates the ladder against the current weaviate tags: 1.37 and 1.38 have newer patches (1.37.16, 1.38.14). The final rung stays at 1.39.2, which is what langgenius/dify#38214 now pins, so the volume does not end up ahead of Dify's image. Also corrects the verification snippet. Dify's gen_collection_name_by_id replaces every hyphen in the knowledge base ID with an underscore, so a UUID pasted verbatim into Vector_index_<dataset_id>_Node never matches a real collection, and hyphens are invalid in a GraphQL field name, so the Aggregate count fails outright. The snippet now shows a concrete name and points at the schema check as the source of truth. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
dudanogueira
force-pushed
the
docs/weaviate-server-upgrade-path
branch
from
September 8, 2026 19:41
b74c1c4 to
8c4b1aa
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new Weaviate server upgrade page is only added for en/ (and only wired into the English nav), but the corresponding zh/ and ja/ pages/nav entries are missing despite the repo requirement to ship en/zh/ja together.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Lite
Comment on lines
742
to
750
| "group": "Troubleshooting", | ||
| "pages": [ | ||
| "en/self-host/deploy/troubleshooting/common-issues", | ||
| "en/self-host/deploy/troubleshooting/docker-issues", | ||
| "en/self-host/deploy/troubleshooting/integrations", | ||
| "en/self-host/deploy/troubleshooting/storage-and-migration", | ||
| "en/self-host/deploy/troubleshooting/weaviate-v4-migration" | ||
| "en/self-host/deploy/troubleshooting/weaviate-v4-migration", | ||
| "en/self-host/deploy/troubleshooting/weaviate-server-migration-path" | ||
| ], |
RiskeyL
added a commit
that referenced
this pull request
Sep 10, 2026
* docs: sync documentation for ce 1.17.1 (#1025) * docs: sync api specs and self-host docs for ce 1.17.1 * docs: document the difyctl help compact discovery flow * docs: retranslate team members zh/ja and correct the owner role * Correct markdown formatting in help.mdx Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: add weaviate server upgrade path guide The existing v4 migration guide stops at server 1.27, but Dify now bundles 1.39 (langgenius/dify#38214). Existing deployments cannot jump that gap in one step: Weaviate does not test or support skipping minor versions. Adds a sibling page with the one-minor-at-a-time ladder and the two operational details that decide whether vectors survive it — graceful shutdown, which a hard kill silently costs you in HNSW recall, and the post-restart index-mount race. Cross-links both directions with the v4 page. en, zh and ja, with nav mirrored across all three sections. * fix: correct weaviate client versions in the compatibility matrix The matrix listed v4.17.0 for every release from 1.9.2 onward and capped server coverage at "tested up to 1.33.1". Both are stale: the client moved to 4.20.4 in 1.13.1 and 4.20.5 in 1.14.0, and the server bound was a moving target that went out of date rather than a real limit. Splits the client rows at their actual boundaries, replaces the tested-up-to note with the reason the server column has no upper bound, and points readers at the server upgrade path for external instances. Also replaces the hardcoded `pip install weaviate-client==4.17.0` fix with `uv sync`, so source installs get whatever version their checkout pins instead of being pinned to a version Dify stopped shipping. * fix: drop hard-coded step counts and correct a zh phrasing Review feedback on #940: - The warning said "twelve-step ladder" and the blast-radius note said "twelve-version jump" while the table lists thirteen rungs. Both counts are now phrased so they stay correct if the ladder changes. - zh used 回合到 for backporting, which does not read as Chinese. Rewritten as 合入. Applied to ja as well, where the same counts appeared as 10 段階 and 10 以上のバージョン. * fix: address review feedback on the weaviate upgrade path Re-validated the ladder end to end before rewriting: a volume seeded on 1.27.0 was walked through all 13 rungs, verified at each with both weaviate-client 4.20.5 and 4.22.0 (28/28 runs passed on object count, byte-exact vectors, near_vector recall, BM25 and a write round-trip). Sequencing: the page no longer claims the image bump has happened. langgenius/dify#38214 is still open and 1.17.0 still pins semitechnologies/weaviate:1.27.0, so the opening now describes a pin that is moving and reads correctly before and after that PR lands. Corrections from the re-run: - Object count used /v1/objects?limit=1 and read totalResults, which is the page length, not the collection total (always 1). Replaced with a GraphQL Aggregate query. - Every curl targeted localhost:8080, which the default compose file does not publish. All checks now run through docker compose exec against the container, using busybox wget since the image has no curl or python. - The hard-kill section claimed the index "recovers once rebuilt". It does not. A kill left 20 of 700 objects in the store but off the HNSW graph, and they stayed missing across three restarts and a rewrite, with nothing logged. Rewritten with the measured numbers and the real remedy. - The mount-race error text was wrong: no restart produced "non-existing index". The window returns 404 and a GraphQL "no schema is present", and it grows from under 0.3s to 4-9s at 1.31. Replaced with measurements. - Tail rungs moved to 1.37.15 and 1.38.13; the final rung stays at Dify's pin rather than the newest patch, so the ladder cannot overshoot it. - Weaviate supports three minor versions in total, not four. - docker compose stop -t 120 is now used in all four operational blocks, and sudo cp -a replaces cp -r in backup and rollback. - Client guidance points at the version each Dify release pins. - Pre-1.27 readers are routed to the v4 guide by version, not "1.19". - Dify does not set a distance metric; cosine is the server default. - Registry change to cr.weaviate.io is now explained at the ladder. Compatibility matrix restored to patch precision, corrected against the dependency history: 4.20.4 spans 1.13.1-1.13.3, 4.20.5 spans 1.14.0-1.16.1, and 1.17.0 ships 4.22.0. The uv sync block is split out with an explicit cd to the repo root, since it fails if copied from docker/. zh and ja mirrored in the same pass; zh description switched from 自托管 to the glossary's 自部署. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD * fix: move the final rung to weaviate 1.39.2 langgenius/dify#38214 now pins 1.39.2, so the ladder's last rung follows it. The rung must match the pin exactly: landing the volume on a different patch and then applying the compose file is the downgrade the page warns about. Validated the changed step rather than assuming it. Restored the volume snapshot taken after 1.38.13 and stepped it to 1.39.2: all checks pass with both weaviate-client 4.20.5 and 4.22.0, the index-mount gap is 7.8s (inside the documented 4-9s band), and totalResults behaves as documented (1 at limit=1, 200 at limit=250). Re-ran the hard-kill experiment on 1.39.2 too, which reproduces the same 20-of-700 unreachable objects with no recovery across restarts, so the measured figures now cite one version throughout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD * style: left-align the weaviate compatibility matrix columns Matches the separator style already used by the tables in weaviate-server-migration-path.mdx. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * refactor: scope the weaviate upgrade path pr to english only Per review feedback on #940, the maintainers will handle the zh/ja alignment once the English content is settled. Drop the zh/ja copies of weaviate-server-migration-path, revert the zh/ja weaviate-v4-migration edits to main, and remove the matching zh/ja navigation entries so no section points at a missing page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * fix: refresh weaviate tail rungs and correct the collection name Revalidates the ladder against the current weaviate tags: 1.37 and 1.38 have newer patches (1.37.16, 1.38.14). The final rung stays at 1.39.2, which is what langgenius/dify#38214 now pins, so the volume does not end up ahead of Dify's image. Also corrects the verification snippet. Dify's gen_collection_name_by_id replaces every hyphen in the knowledge base ID with an underscore, so a UUID pasted verbatim into Vector_index_<dataset_id>_Node never matches a real collection, and hyphens are invalid in a GraphQL field name, so the Aggregate count fails outright. The snippet now shows a concrete name and points at the schema check as the source of truth. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJrBcM2YWVgeGEqAr2FQXm * Update Weaviate Migration Guide for client v4 and server 1.27 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * chore: merge main into release/1.17.1 and resort the api specs (#1028) * feat: put the writing standard first in the docs pipeline and add the editor test (#1021) * feat: put the writing standard first in the docs pipeline and add the editor test Rewrite dify-docs-write so the drafting turn holds the standard, the facts, and a reference page rather than the check procedures: reading indexed by stage, a fresh drafting agent, an outline gate keyed to reader questions, the research summary shown at the scope gate, three revision tiers, and an editor test that judges the writing before any linter. Open the style guide with "What a Good Page Does" and two worked examples from the Cloud New Agent pages. De-prescribe the CLI, guides, reader-test, release-sync, and feature-research packs; retire row and print vocabulary; state the translation, verification, and check rules once. Move repo-only facts into the guides index and reduce AGENTS.md to the entry point and repo rules. * fix: address review on the writing guides and pipeline Point the Columns block at the alt-text rule instead of restating it, lowercase the glossary row for agentic workflow with its plural note, scope the editor test to the English page in the guides index and the pipeline, and finish the fragment in the style guide's example lead-in. * fix: spell out the task-page exemplar's path in the pipeline and the editor test * fix: make pack reads conditional and align heading case and bold punctuation in the guides * fix: correct the Frame example, the zh punctuation after examples, and the glossary row's casing note * style: sort openapi keys while preserving api navigation (#1022) --------- Co-authored-by: Stephen Zhou <hi@hyoban.cc> * docs: complete Weaviate 1.17.1 migration guidance * docs: stop Weaviate before final Dify upgrade * docs: handle Weaviate migration re-entry * fix: correct the pnpm version and unify the rate limit wording * docs: document the weaviate host port variables (#1033) EXPOSE_WEAVIATE_GRPC_PORT is new to the 1.17.1 build: dify#38214 gave it its first .env.example entry, though docker-compose.middleware.yaml has consumed it since 2025-10-13. EXPOSE_WEAVIATE_PORT is its twin and was already undocumented, so both land together in the Weaviate Service accordion. Both are middleware-stack only; the full Compose stack keeps Weaviate on an internal network. Each row links to the client-side endpoint variable it must be kept in sync with, which sits about 1100 lines away. --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Duda Nogueira <dudanogueira@gmail.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Stephen Zhou <hi@hyoban.cc> Co-authored-by: Yajing Wang <yajing@Yajings-MacBook-Air.local> Co-authored-by: Yajing Wang <101789361+Ill-donut@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
self-host/deploy/troubleshooting/weaviate-server-migration-path, a sibling to the existing Weaviate v4 migration guide, covering how to move a self-hosted Weaviate server across minor versions.The existing page ends at server
1.27. langgenius/dify#38214 moves Dify's bundled image to1.39.2, and existing deployments cannot cross that gap in one step — Weaviate does not test or support skipping minor versions, and any release may carry an on-disk migration that expects the previous version to have run at least once. Without this page, a self-hosted user who pulls that upgrade has no documented path forward.The page is written so it is correct both before and after that bump ships: it describes a pin that is moving rather than asserting it has moved. Dify
1.17.0still pinssemitechnologies/weaviate:1.27.0, so nothing here depends on the release landing first.What the Page Covers
1.27to1.39.2, landing on the latest patch of each minor — with the final rung pinned to whateverdocker-compose.yamlpins, since overshooting it and then applying Dify's pin is a downgrade onto a volume the newer binary already wrote to.semitechnologies/weaviatetocr.weaviate.io/semitechnologies/weaviate, explained so readers know it is deliberate.Validation
Everything above was measured, not inferred. A volume seeded on
1.27.0was walked one minor at a time to1.39.2and verified at every rung with bothweaviate-client4.20.5 and 4.22.0 — object count, byte-exact vectors for all 200 objects,near_vectorrecall, self-retrieval, recall@20 against brute-force ground truth, BM25, and a write round-trip. All 28 verification runs passed.Three findings changed what the page says:
Hard kills cause permanent, silent recall loss. A
docker killright after importing 500 objects into a 700-object collection left the count at 700 whilenear_vectoratlimit: 700returned 680. The objects are fine — all 700 list, all 500 imported are found by BM25, fetch-by-ID returns exact vectors — but 20 are unreachable by vector search. It does not heal: identical after the restart, after a graceful stop/start, after a second one, and after re-writing the same objects, with no background rebuild over a 10-minute observation. It is also silent in the logs (110 info lines, 6 unrelated warnings, nothing about the commit log). The only detection is aggregate count vsnear_vectoratlimit=count.The index-mount window is real and version-dependent.
/v1/metaanswers ~2.3s after start on every version, but the first successful collection query lags it by under 0.3s on 1.27–1.30 and by 4–9s from 1.31 onward. Inside that window a browse returns404and GraphQL returns422 no graphql provider present … no schema is present— not the "non-existing index" error an earlier draft claimed; that string appeared in none of the 13 restarts.totalResultsis the page length, not the collection total. Confirmed in Weaviate's handler (TotalResults: int64(len(list))) and empirically:limit=1→ 1,limit=250→ 200. All count checks use a GraphQLAggregatequery instead.Commands Run Inside the Compose Network
Dify's default
docker-compose.yamlpublishes no host port for Weaviate, so every check goes throughdocker compose execrather thanlocalhost:8080. The image is Alpine-based with busyboxwgetand nocurlorpython3, so requests usewgetand JSON is formatted host-side. Verified working, including--post-datafor the GraphQL count, and on the profile-gatedweaviateservice regardless ofCOMPOSE_PROFILES.Also Fixes the Stale Compatibility Matrix
The v4 page's matrix listed
v4.17.0for every release from 1.9.2 onward and capped the server column at "tested up to 1.33.1". Corrected against the actual dependency history, verified tag by tag:api/providers/vdb/vdb-weaviate/pyproject.tomlat 1.14.0The "tested up to" note is replaced rather than re-pinned: it was a moving target that goes stale on its own, so the page now explains why the server column has no upper bound and sends readers with an external Weaviate to the upgrade path.
The same commit replaces a hardcoded
pip install weaviate-client==4.17.0withuv sync --project api --group vdb-weaviate, split into its own block with an explicitcd /path/to/dify— it fails if copied fromdocker/.Notes for Review
AGENTS.md. Nav mirrored across all threedocs.jsonsections.weaviate-v4-migration: that page covers 1.19.0–1.26.x and the schema migration, this one continues from 1.27.check-format-en.py/check-format-cjk.pylinters clean.4.20.4row spans through 1.13.3 (not just 1.13.1), and the hard-kill failure is permanent, not a temporary degradation.🤖 Generated with Claude Code
https://claude.ai/code/session_01CdUgDmCZupD73cZ3LqWjuD