docs: note sweep+accelerated DHT client limitation (#11084)
document known 0.39 limitation where sweep provider may fail to estimate DHT size when accelerated client is still crawling the network, resulting in single-region mode without efficiency gains. also remove accelerated client recommendation from changelog since it may mislead users into enabling both together.
Marcin Rataj committed
Nov 28, 2025 at 23:10 UTC
af2e7e195385e3f137c0a0dd0a97afc713944a14
3 files changed
+14
-1
docs/changelogs/v0.39.md
+2
-1
@@ -46,6 +46,7 @@ The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now
46
- If you were using the default settings, you'll automatically get the sweep provider
47
- To opt out and return to legacy behavior: `ipfs config --json Provide.DHT.SweepEnabled false`
48
- Providers with medium to large datasets may need to adjust defaults; see [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning)
49
+- When `Routing.AcceleratedDHTClient` is enabled, full sweep efficiency may not be available yet; consider disabling the accelerated client as sweep is sufficient for most workloads. See [caveat 4](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingaccelerateddhtclient).
50
51
**New features available with sweep mode:**
52
@@ -77,7 +78,7 @@ ipfs dag import file.car # Same for CAR imports
78
79
**Configuration:** Set defaults via `Import.FastProvideRoot` (default: `true`) and `Import.FastProvideWait` (default: `false`). See `ipfs add --help` and `ipfs dag import --help` for more details and examples.
80
80
-This optimization works best with the sweep provider and accelerated DHT client, where provide operations are significantly faster. Automatically skipped when DHT is unavailable (e.g., `Routing.Type=none` or delegated-only configurations).
81
+Fast root CID provide is automatically skipped when DHT routing is unavailable (e.g., `Routing.Type=none` or delegated-only configurations).
82
83
#### ⏯️ Provider state persists across restarts
84
docs/config.md
+4
@@ -2640,6 +2640,10 @@ prepared. This means operations like searching the DHT for particular peers or c
2640
- You can see if the DHT has been initially populated by running `ipfs stats dht`
2641
3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against
2642
them
2643
+4. (⚠️ 0.39 limitation) When used with [`Provide.DHT.SweepEnabled`](#providedhtsweepenabled), the sweep provider may
2644
+fail to estimate DHT size during the accelerated client's network crawl, resulting in all CIDs grouped into a
2645
+single region. Content still gets reprovided, but without sweep efficiency gains. Consider disabling the
2646
+accelerated client when using sweep mode.
2647
2648
Default: `false`
2649
docs/provide-stats.md
+8
@@ -221,6 +221,11 @@ reprovide duration gives CIDs/min/worker.
221
222
Number of regions reprovided in the last cycle.
223
224
+> [!NOTE]
225
+> (⚠️ 0.39 limitation) If this shows 1 region while using
226
+> [`Routing.AcceleratedDHTClient`](./config.md#routingaccelerateddhtclient), sweep mode lost
227
+> efficiency gains. Consider disabling the accelerated client. See [caveat 4](./config.md#routingaccelerateddhtclient).
228
+
229
## Workers
230
231
### Active workers
@@ -278,6 +283,9 @@ To check if your provide system has sufficient capacity:
283
- High active workers with growing reprovide queue: Need more workers or network connectivity is limiting throughput
284
- Low active workers with non-empty reprovide queue: Workers may be waiting for network or DHT operations
285
- Check [Reachable peers](#reachable-peers) to diagnose network connectivity issues
286
+- (⚠️ 0.39 limitation) If [Regions scheduled](#regions-scheduled) shows 1 while using
287
+ [`Routing.AcceleratedDHTClient`](./config.md#routingaccelerateddhtclient), consider disabling
288
+ the accelerated client to restore sweep efficiency. See [caveat 4](./config.md#routingaccelerateddhtclient).
289
290
## See Also
291