Why IPFS Provider Records Expire and Get Renewed

IPFS provider records, the DHT entries that let other peers find who has a given CID, are not permanent once published. They expire, and if a node stops re-announcing, its content quietly falls out of the DHT even though the node is still online and still holding every block. This is a detail the DHT article earlier in this series didn't cover: storing content and staying findable are two separate, ongoing jobs, and reproviding is what keeps the second one true over time.

TL;DR:

• Advertising a CID to the DHT once is not enough forever; provider records have an expiration, and un-refreshed records disappear from the DHT even if the underlying content never moves
• Kubo's current defaults expire a DHT-published provider record after 48 hours, and run a background reprovide cycle every 22 hours, comfortably inside that window
• The 22-hour interval isn't arbitrary, it's set specifically to leave enough margin for a full reprovide pass to finish before the previous records expire
• If a reprovide cycle takes longer than 22 hours to complete, the next cycle gets skipped entirely, and provider records that didn't get refreshed in time start expiring from the DHT
• Being pinned and being discoverable are not the same guarantee; a pinning service's real job includes running this reprovide process continuously, not just holding the blocks

Storing Content and Advertising It Are Different Jobs

This series' DHT article covered how a node announces content it holds: a provider PUT, storing a record at the K=20 peers closest to that content's hashed address, so a later lookup can find them. What it didn't cover is that this announcement isn't a one-time event. A node can hold a block indefinitely, pinned, protected from garbage collection, sitting on disk exactly as it always has, while the DHT record pointing to it as a provider quietly expires and vanishes. From that point, the block still exists, but nobody running a DHT lookup will find it there, because nothing currently in the DHT says this node has it.

Why Records Expire At All

A DHT with records that never expired would accumulate stale entries forever, peers that went offline months ago, content that got deleted, nodes that changed their provide strategy, all still showing up in lookups as if they were current. Expiration is the DHT's way of keeping its own state roughly accurate without requiring an explicit "I don't have this anymore" message from every peer that stops providing something, which would be unreliable to depend on anyway since a peer can disappear without sending anything at all.

The Current Numbers: 48-Hour Expiry, 22-Hour Reprovide

Kubo's defaults, evolved over several releases, currently set a DHT-published provider record's expiration at 48 hours from when it was last published, and run a background reprovide cycle, re-announcing every CID matching the node's provide strategy, every 22 hours. That 22-hour figure is deliberately conservative relative to the 48-hour expiry: it leaves roughly a full cycle's worth of margin, so a provider record gets refreshed well before it would otherwise lapse, rather than cutting it close to the deadline every time.

What Happens If Reproviding Falls Behind

The margin exists for a reason: if a full reprovide pass takes longer than 22 hours to complete, perhaps because a node is advertising a very large number of CIDs, the next scheduled cycle gets skipped entirely rather than overlapping with the one still running. If that keeps happening across multiple cycles, provider records that never got refreshed in time start crossing their 48-hour expiration and disappearing from the DHT, even though nothing about the underlying pinned content changed. This is a real operational failure mode distinct from data loss: the content is intact and pinned, it has simply become unfindable through the normal discovery path.

Reproviding Is Not the Same Guarantee As Pinning

Pinning, covered in this series' garbage collection article, protects content from local deletion. Reproviding keeps that same content discoverable by peers who don't already know where it is. A node can get one right and the other wrong independently: content can be perfectly pinned and completely undiscoverable if reproviding has stalled, and in principle content could stay discoverable for a little while even after being unpinned, until the next garbage collection run actually removes the blocks the provider record was pointing to. Treating "pinned" as the whole story skips this second, ongoing requirement.

Where This Matters for a Pinning Service

This is exactly the operational gap a pinning service like AIOZ Pin exists to close on an ongoing basis, not just at the moment a file gets uploaded. Keeping pinned content genuinely retrievable means running both halves continuously: holding the blocks, and keeping their provider records fresh in the DHT so the rest of the network can still find them. A single laptop that pins a file and then goes to sleep for a few days fails at the second half well before it fails at the first, its provider records expire from the DHT long before anything happens to the blocks sitting on its disk. Infrastructure that stays online and keeps reproviding as a matter of course is what makes the difference between technically-pinned and actually-discoverable, which is the real substance behind the replication and persistence claims covered in this series' AIOZ Pin article.

Frequently Asked Questions

Does pinning a file also keep it discoverable on the DHT? Pinning protects a file from local deletion. Staying discoverable requires the node to also keep re-announcing (reproviding) the file's provider record before it expires, which is a separate, ongoing process.

How long does an IPFS provider record last before it expires? Under kubo's current defaults, 48 hours from when it was last published, with a background reprovide cycle running every 22 hours to refresh it well before that.

Why is the reprovide interval shorter than the expiration time? To leave margin: refreshing every 22 hours against a 48-hour expiry means a full reprovide cycle has room to complete even if it runs a little long, without records lapsing.

What happens if a node's reprovide cycle takes too long? The next scheduled cycle gets skipped rather than overlapping with the one still in progress. If this happens repeatedly, unrefreshed provider records start expiring from the DHT.

Can content be pinned but still unfindable on the network? Yes. If its provider records have expired without being refreshed, the content is still safely stored, but a DHT lookup for it won't currently return anything.

Does AIOZ Pin handle reproviding for pinned content? Keeping pinned content genuinely discoverable, not just stored, requires the hosting infrastructure to keep reproviding continuously, which is part of what running always-on pinning infrastructure like AIOZ Pin's actually involves, distinct from a single node that goes offline between uploads.

Related Reading

• How IPFS Finds and Retrieves Your Files: DHT Provider Records and Bitswap Explained - the provider-record mechanism this article covers the expiration and renewal side of
• What Happens When You Unpin a File on IPFS: Garbage Collection Explained - the separate local-storage guarantee reproviding does not replace
• How AIOZ Pin Actually Keeps Your Files Online: Replication, CIDs, and Proof-of-Storage - the product-level persistence this operational detail underpins
• IPNS: Mutable Pointers to Immutable IPFS Content - a different record type in the same DHT that follows a similar publish-and-expire pattern
• Delegated Routing: How Light Clients Skip Running a DHT - the lighter-weight HTTP alternative for clients that don't want to reprovide anything themselves
• Optimistic Provide: How IPFS Made Publishing 10x Faster - a real, measured speedup to the initial provide step this article's renewal cycle keeps fresh afterward

References

• ipfs/kubo Issue #9389: New defaults for Provider Record Republish and Expiration
• IPFS Docs: The DHT