Why IPFS Used to Give You Different CIDs for the Same File

Add the exact same file to IPFS through Kubo, then through Helia, then through Singularity, and for years you could get three different CIDs back. Not because the content changed, but because each tool sliced the file into different-sized chunks and built a different-shaped DAG on top of it. If your whole mental model of content addressing is "same bytes in, same CID out," that result looks like a bug. Two separate threads on the IPFS forums exist asking exactly this question. As of March 2026, a real fix landed: IPIP-0499. Here is what was actually broken, and what changed.

TL;DR:

• A CID is a hash of a file's Merkle DAG structure, not just its raw bytes, so two tools that build that structure differently produce two different CIDs from identical content
• The specific culprits: chunk size, DAG fan-out (links per node), and the threshold for switching a directory to a HAMT, all of which used to vary by implementation
• IPIP-0499 fixes this by defining two named, complete parameter profiles: unixfs-v1-2025 (the new default, which every implementation must support) and unixfs-v0-2015 (legacy, optional, for matching old Kubo output)
• The new default is also more efficient: 1 MiB chunks and 1,024 links per DAG node (up from 256 KiB and 174), cutting a 1 TiB file's DAG depth from 4 levels to 3 with roughly 4x fewer total nodes
• Deterministic CIDs matter for verification at scale: you can now compare two CIDs directly instead of fetching both files and recomputing their DAGs to check if they actually match

The Problem: A CID Hashes Structure, Not Just Bytes

A CID is not a hash of a file's raw bytes the way a plain SHA-256 checksum is. It's the hash of the root node of that file's Merkle DAG, and building that DAG requires a series of implementation choices: how big each chunk is, how many child links a DAG node can hold before splitting, and at what point a directory switches from a flat list to a HAMT structure. Change any of those choices and you get a differently-shaped DAG, which means a different root hash, which means a different CID, even though the underlying file content is byte-for-byte identical.

Before 2026, those choices were not standardized across implementations. Kubo, Helia, and Singularity each shipped with their own defaults, tuned independently over years of separate development. Someone uploading the same file to two different tools, or comparing a CID from one tool against a CID computed by another, could hit a false mismatch that had nothing to do with the content itself.

IPIP-0499: Two Named Profiles Instead of Per-Tool Defaults

The fix, merged into the IPFS specification in March 2026, is IPIP-0499. Instead of leaving chunking and DAG parameters as implementation-specific defaults, it defines two complete, named profiles that any conforming implementation can point to:

• unixfs-v1-2025: the new default. Implementations MUST support it.
• unixfs-v0-2015: the legacy profile, kept for implementations that need to reproduce historical Kubo output. Implementations MAY support it, but it's not required.

The practical effect: two implementations that both target unixfs-v1-2025 will produce the same CID for the same input, every time. That's the property "content addressing" was always supposed to guarantee and, until this update, didn't fully deliver across tool boundaries.

The New Default Is Also Faster

unixfs-v1-2025 isn't just a standardization exercise, it changes the actual numbers. Chunk size moves from 256 KiB to 1 MiB, and the maximum links per DAG node moves from 174 to 1,024. Bigger chunks and wider nodes mean a shallower tree for the same amount of data: a 1 TiB file needs 3 levels of DAG traversal under the new default instead of 4, with roughly 4x fewer total DAG nodes.

Fewer, shallower levels means less random-access latency when seeking into a large file, and fewer individual block CIDs that need to be announced to routing infrastructure like the Amino DHT when the file gets provided to the network. The determinism fix and the performance gain came bundled together, not as two separate tradeoffs.

Why This Matters for Verification at Scale

The most concrete payoff of deterministic CIDs is what it does to verification cost. Without a shared profile, confirming that two CIDs point to "the same content" required fetching both files and recomputing their DAGs to check, since the CIDs alone couldn't tell you whether a mismatch meant different content or just different chunking settings. With both sides on the same profile, comparing the CIDs directly is enough. No fetch, no recompute.

That distinction matters directly for the CID-recompute-and-compare verification workflow already covered on this site. If you're comparing a CID returned by one tool against a CID computed independently by a different one, and they don't match, the honest first question is now "were both sides using the same UnixFS profile," not "did the content change." AIOZ Pin's own API documentation doesn't publish which specific profile its pinning pipeline targets internally, so treat that as a real open question to check rather than an assumption, especially if you're cross-verifying CIDs generated outside AIOZ Pin against ones pinned through it.

What This Doesn't Change

IPIP-0499 doesn't retroactively alter CIDs that already exist. A file pinned last year under whatever defaults were in place then keeps the CID it already has; nothing about this update rewrites history or invalidates old pins. It also doesn't force every implementation onto identical behavior forever, the legacy unixfs-v0-2015 profile exists specifically so tools that need to reproduce old Kubo-era output still can. What it does is give every implementation going forward a shared, named target to converge on, instead of each one quietly drifting on its own defaults.

Frequently Asked Questions

Why did the same file get different CIDs on different IPFS tools? Because a CID hashes a file's Merkle DAG structure, not just its raw bytes, and different tools used different chunk sizes, DAG node widths, and HAMT thresholds when building that structure, producing different DAGs, and therefore different CIDs, from identical content.

What is IPIP-0499? An IPFS specification change, merged in March 2026, that defines two named UnixFS parameter profiles, unixfs-v1-2025 and unixfs-v0-2015, so that any implementation targeting the same profile produces identical CIDs for identical input.

Does this change CIDs I already have? No. Existing CIDs stay exactly as they are. The new profile only affects how new content gets chunked and hashed going forward.

Is the new default just about consistency, or is it faster too? Both. unixfs-v1-2025 uses 1 MiB chunks and 1,024 links per DAG node, versus 256 KiB and 174 previously, cutting DAG depth for a 1 TiB file from 4 levels to 3 with about 4x fewer total nodes.

Which implementations support IPIP-0499 today? On the Go side: Kubo 0.40+, boxo 0.37+, go-ipfs-cmds 0.16+. On the JS side: helia/unixfs 7.0.3+ and ipfs-unixfs-importer 16.1.1+.

If two CIDs for what should be the same file don't match, what should I check first? Whether both tools that generated the CIDs were targeting the same UnixFS profile, before assuming the underlying content actually differs.

Related Reading

• How IPFS Shards Large Directories: The HAMT - the directory-sharding threshold that IPIP-0499's profiles also standardize
• How IPFS Splits Files Into Blocks: Chunking Explained - the chunk-size mechanics this update changes the defaults for
• Anatomy of a CID: Decoding an IPFS Content Identifier - what actually goes into a CID's structure
• Verifying NFT Content Against Its CID - the recompute-and-compare workflow this update's profile mismatch caveat directly affects
• Optimistic Provide: How IPFS Made Publishing 10x Faster - the DHT-announcement step that benefits from fewer, shallower DAG nodes
• How IPFS Finds and Retrieves Files: DHT and Bitswap - the Amino DHT that receives fewer provider announcements under the new default

References

• IPIP-0499: Updating IPFS Standards for Consistent, Reproducible CIDs
• IPIP-0499 full specification