docs/changelogs/v0.38.md
<a href="https://ipshipyard.com/"></a>
This release was brought to you by the Shipyard team.
ipfs files write fixesKubo 0.38.0 simplifies content announcement configuration, introduces an experimental sweeping DHT provider for efficient large-scale operations, and includes various performance improvements.
This release migrates the repository from version 17 to version 18, simplifying how you configure content announcements.
The old Provider and Reprovider sections are now combined into a single Provide section. Your existing settings are automatically migrated - no manual changes needed.
Migration happens automatically when you run ipfs daemon --migrate. For manual migration: ipfs repo migrate --to=18.
Read more about the new system below.
A new experimental DHT provider is available as an alternative to both the default provider and the resource-intensive accelerated DHT client. Enable it via Provide.DHT.SweepEnabled.
How it works: Instead of providing keys one-by-one, the sweep provider systematically explores DHT keyspace regions in batches.
<picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/f6e06b08-7fee-490c-a681-1bf440e16e27"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/e1662d7c-f1be-4275-a9ed-f2752fcdcabe"> </picture>The diagram shows how sweep mode avoids the hourly traffic spikes of Accelerated DHT while maintaining similar effectiveness. By grouping CIDs into keyspace regions and processing them in batches, sweep mode reduces memory overhead and creates predictable network patterns.
Benefits for large-scale operations: Handles hundreds of thousands of CIDs with reduced memory and network connections, spreads operations evenly to eliminate resource spikes, maintains state across restarts through persistent keystore, and provides better metrics visibility.
Monitoring and debugging: Legacy mode (SweepEnabled=false) tracks provider_reprovider_provide_count and provider_reprovider_reprovide_count, while sweep mode (SweepEnabled=true) tracks total_provide_count_total. Enable debug logging with GOLOG_LOG_LEVEL=error,provider=debug,dht/provider=debug to see detailed logs from either system.
[!IMPORTANT] The metric
total_provide_count_totalwas renamed toprovider_provides_totalin Kubo v0.39 to follow OpenTelemetry naming conventions. If you have dashboards or alerts monitoring this metric, update them accordingly.
[!NOTE] This feature is experimental and opt-in. In the future, it will become the default and replace the legacy system. Some commands like
ipfs stats provideandipfs routing provideare not yet available with sweep mode. Runipfs provide --helpfor alternatives.
For configuration details, see Provide.DHT. For metrics documentation, see Provide metrics.
Kubo now exposes DHT metrics from go-libp2p-kad-dht, including total_provide_count_total for sweep provider operations and RPC metrics prefixed with rpc_inbound_ and rpc_outbound_ for DHT message traffic. See Kubo metrics documentation for details.
[!IMPORTANT] The metric
total_provide_count_totalwas renamed toprovider_provides_totalin Kubo v0.39 to follow OpenTelemetry naming conventions. If you have dashboards or alerts monitoring this metric, update them accordingly.
Gateway error pages now provide more actionable information during content retrieval failures. When a 504 Gateway Timeout occurs, users see detailed retrieval state information including which phase failed and a sample of providers that were attempted:
Gateway.DiagnosticServiceURL(default:https://check.ipfs.network): Configures the diagnostic service URL. When set, 504 errors show a "Check CID retrievability" button that links to this service with?cid=<failed-cid>for external diagnostics. Set to empty string to disable.- Enhanced error details: Timeout errors now display the retrieval phase where failure occurred (e.g., "connecting to providers", "fetching data") and up to 3 peer IDs that were attempted but couldn't deliver the content, making it easier to diagnose network or provider issues.
- Retry button on all error pages: Every gateway error page now includes a retry button for quick page refresh without manual URL re-entry.
The Web UI has been updated to v4.9 with a new Diagnostics screen for troubleshooting and system monitoring. Access it at http://127.0.0.1:5001/webui when running your local IPFS node.
| Diagnostics: Logs | Files: Check Retrieval | Diagnostics: Retrieval Results |
|---|---|---|
| Debug issues in real-time by adjusting log level without restart (global or per-subsystem like bitswap) | Check if content is available to other peers directly from Files screen | Find out why content won't load or who is providing it to the network |
| Peers: Agent Versions | Files: Custom Sorting |
|---|---|
| Know what software peers run | Find files faster with new sorting |
Additional improvements include a close button in the file viewer, better error handling, and fixed navigation highlighting.
ipfs pin ls <cid> --names now correctly returns pin names for specific CIDs (#10649, boxo#1035), RPC no longer incorrectly returns names from other pins (#10966), and pin names are now limited to 255 bytes for better cross-platform compatibility (#10981).
ipfs files write fixesIdentity CID size limits are now enforced
This release enforces a maximum of 128 bytes for identity CIDs (IPIP-512) - attempting to exceed this limit will return a clear error message.
Identity CIDs use multihash 0x00 to embed data directly in the CID without hashing. This experimental optimization was designed for tiny data where a CID reference would be larger than the data itself, but without size limits it was easy to misuse and could turn into an anti-pattern that wastes resources and enables abuse.
ipfs add --inline-limit and --hash=identity now enforce the 128-byte maximum (error when exceeded)ipfs files write prevents creation of oversized identity CIDsMultiple ipfs files write bugs have been fixed
This release resolves several long-standing MFS issues: raw nodes now preserve their codec instead of being forced to dag-pb, append operations on raw nodes work correctly by converting to UnixFS when needed, and identity CIDs properly inherit the full CID prefix from parent directories.
Improvements to the providing system in the last release (provide blocks according to the configured Strategy) left out Filestore and Urlstore blocks when the "all" strategy was used. They would only be reprovided but not provided on write. This is now fixed, and both Filestore blocks (local file references) and Urlstore blocks (HTTP/HTTPS URL references) will be provided correctly shortly after initial add.
The new Internal.MFSNoFlushLimit configuration option prevents unbounded memory growth when using --flush=false with ipfs files commands. After performing the configured number of operations without flushing (default: 256), further operations will fail with a clear error message instructing users to flush manually.
boxo to v0.35.0go-libp2p-kad-dht to v0.35.0ipfs-webui to v4.9.1 (incl. v4.9.0)--flush=false (#10985) (ipfs/kubo#10985)flush=false (#10971) (ipfs/kubo#10971)ipfs pin ls <cid> --names (#10970) (ipfs/kubo#10970)MaxRangeRequestFileSize protection (#1043) (ipfs/boxo#1043)CheckIfPinnedWithType for efficient checks with names (#1035) (ipfs/boxo#1035)time.Duration for rebroadcast delay (#1027) (ipfs/boxo#1027)retrieval.RetrievalState to retrieval.State (#1026) (ipfs/boxo#1026)@masih form CODEOWNERS (ipld/go-car#605)| Contributor | Commits | Lines ยฑ | Files Changed |
|---|---|---|---|
| Guillaume Michel | 62 | +15401/-5657 | 209 |
| Marcin Rataj | 33 | +9540/-1734 | 215 |
| Andrew Gillis | 29 | +771/-1093 | 70 |
| Hlib Kanunnikov | 2 | +350/-0 | 5 |
| Rod Vagg | 3 | +260/-9 | 4 |
| Hector Sanjuan | 4 | +188/-33 | 11 |
| Jakub Sztandera | 1 | +67/-15 | 3 |
| Masih H. Derkani | 1 | +1/-2 | 2 |
| Dominic Della Valle | 1 | +2/-1 | 1 |
Fixes migration panic on Windows when upgrading from v0.37 to v0.38 ("panic: error can't be dealt with transactionally: Access is denied").
Updates go-ds-pebble to v0.5.3 (pebble v2.1.0).
| Contributor | Commits | Lines ยฑ | Files Changed |
|---|---|---|---|
| Marcin Rataj | 2 | +613/-267 | 15 |
| Andrew Gillis | 6 | +148/-22 | 8 |
Provide.DHT.SweepEnabled=trueGetBlocks (ipfs/boxo#1060)| Contributor | Commits | Lines ยฑ | Files Changed |
|---|---|---|---|
| rvagg | 1 | +537/-481 | 3 |
| Carlos Hernandez | 9 | +556/-218 | 11 |
| Guillaume Michel | 3 | +139/-105 | 6 |
| gammazero | 8 | +101/-97 | 14 |
| Hector Sanjuan | 1 | +87/-28 | 5 |
| Marcin Rataj | 4 | +57/-9 | 7 |
| Marco Munizaga | 2 | +42/-14 | 7 |
| Dennis Trautwein | 2 | +19/-7 | 7 |
| Andrew Gillis | 3 | +3/-19 | 3 |
| Rod Vagg | 4 | +12/-3 | 4 |
| web3-bot | 1 | +2/-1 | 1 |
| galargh | 1 | +1/-1 | 1 |