Back

Blog details

The NFT Metadata Problem: When Your IPFS Pin Expires

AIOZ Network
7 min readSeptember 14, 2026
aioz-pin

The NFT metadata problem doesn't show up at mint time. It shows up months or years later, when a collector opens their wallet and sees a broken image icon where their NFT used to be. The token is still there, the transaction still happened, the ownership record is still perfectly intact on-chain. What's missing is everything that made the NFT actually mean something visually, and understanding exactly why that happens, and why it's so hard to fix after the fact, is the case for taking pinning seriously before it becomes a problem instead of after.

TL;DR:

  • A broken NFT doesn't look like an error message, it looks like a placeholder image, a spinning loader that never resolves, or a marketplace listing with no picture and no attributes, while the token itself remains perfectly valid on-chain
  • This is structurally worse than an ordinary broken webpage link: many common NFT contracts have no built-in way to update a tokenURI after minting, so there's often no "just fix the link" option once the underlying content goes offline
  • Link and content rot is a measured, documented phenomenon well beyond NFTs specifically, Pew Research Center found 38% of webpages that existed in 2013 are no longer accessible today, the same decay dynamic an unpinned NFT asset inherits
  • A valid CID is not the same as available content, this series' content-addressing article covers exactly why: the address stays mathematically correct forever, but nothing about it guarantees anyone is still hosting what it points to
  • The specific, common failure pattern is a free trial, a personal node, or an expired pinning subscription that quietly stops hosting the asset long after the mint transaction is finished and forgotten about

Updated Oct 22, 2026: merged our separate post Why NFT Projects Need a Pinning Service, Not Just IPFS into this guide.

What a Broken NFT Actually Looks Like

It's rarely dramatic. A marketplace listing shows a grey placeholder square instead of the artwork. A wallet app shows a token with no image and a name field reading "Unknown" or nothing at all. Sometimes it's a loading spinner that never resolves, the request for the metadata or image technically went out, but nothing answered it. None of this touches the blockchain layer at all, the ownership record, the transaction history, the token ID, all of it stays exactly as valid as the day it was minted. What's broken is entirely off-chain: the JSON metadata file, the image file, or both, sitting at a CID that used to resolve and now doesn't.

A broken link on a regular website is usually fixable in minutes: update the URL, redeploy, done. An NFT doesn't have that same escape hatch by default. Many of the most common, straightforward ERC-721 contract implementations store the tokenURI at mint time with no built-in function to change it afterward, immutability by design, the same property that makes an NFT's ownership record trustworthy in the first place. That means fixing a broken metadata reference isn't a five-minute deploy, it can require a contract upgrade path that may not exist, or simply may not be possible at all for a standard, non-upgradeable contract. The mint already happened. The reference is already set. If what it points to disappears, there frequently isn't a clean way to point it somewhere new.

This isn't a hypothetical edge case dreamed up to sell pinning services. Content and link rot is a well-studied phenomenon on the web generally: Pew Research Center found that 38% of webpages that existed in 2013 are no longer accessible today, over a third of the open web, gone within about a decade. An NFT's off-chain metadata and image are subject to the exact same decay dynamic as any other piece of hosted content, unless something is actively counteracting it. The only thing that changes for an NFT specifically is that the address pointing at that content, unlike a normal URL, was written permanently into a blockchain transaction rather than a webpage someone could quietly update.

Why IPFS Alone Doesn't Solve This

This is the part that gets misunderstood most often: using IPFS for NFT metadata is not, by itself, a persistence guarantee. This series' content-addressing article covers the exact mechanism, a CID is a valid, permanent, mathematically correct address for a specific piece of content, but the address staying valid says nothing about whether any peer on the network is actually still holding that content. An ipfs:// reference in a tokenURI field is real and correctly formed even after every peer that ever hosted the underlying file has gone offline, it just resolves to nothing. Minting on IPFS moves the failure mode; it doesn't remove it.

The Free-Tier Pinning Trap

The specific, common way this actually happens: a project uploads and pins its collection through a free trial, a personal IPFS node running on a laptop, or a pinning subscription that later lapses, and everything works fine at launch, mint day, and for a while after. Then the free trial ends, the laptop gets shut down, or the subscription quietly expires, and nothing dramatic happens immediately, the content just stops being actively pinned anywhere and eventually falls out of the network through ordinary garbage collection. Nobody notices for weeks or months, until a collector happens to load the token and sees a broken image where an actual piece of art used to be.

What It Actually Costs a Project

The blockchain-level facts don't change: the token is still owned, the transaction history is still intact, the smart contract still works exactly as deployed. None of that matters to a collector looking at a broken image in their wallet. A project with widespread broken metadata reads as abandoned or careless regardless of how sound the underlying contract is, and that reputational damage doesn't require a large percentage of a collection to actually break before it registers, a handful of visibly broken tokens circulating on secondary markets is enough to raise doubt about the whole collection's reliability.

Why do NFT projects need a pinning service, not just IPFS?

Your contract stores a pointer such as ipfs://<CID> in the tokenURI, not the image or the JSON. The bytes live off-chain, on whichever IPFS nodes hold them. The AIOZ Pin FAQ describes what those nodes do with content they weren't asked to keep: they cache what passes through, and when the cache fills, garbage collection empties it to make room.

An upload puts a copy on one node. A pin is a standing instruction for that node to keep the blocks and skip them during garbage collection. You can run that node yourself, but then your collection depends on one machine staying online for as long as the tokens exist. A pinning service runs and monitors the nodes for you, which is the whole job.

NFTs add a second risk because each token is two objects. The asset (image, video or audio) and the metadata JSON have separate CIDs, and they are often uploaded separately. If one pin lapses and the other doesn't, you get artwork with no name or attributes, or metadata pointing at an image CID that no longer resolves. Pinning both in the same request removes that split.

Scale multiplies all of this. A 10,000-piece generative drop means 10,000 assets and 10,000 metadata files, and every one of those CIDs has to stay pinned for the life of the collection. Our guide to unpinning and garbage collection shows exactly when unpinned blocks get removed.

The Fix Is Pinning Correctly From the Start, Not Re-Uploading Later

Because fixing a broken tokenURI after the fact is often difficult or impossible, the only reliable answer is to pin the asset and metadata on infrastructure that stays online, before the mint transaction goes out.

On AIOZ Pin, the NFT API takes the asset file and the metadata JSON in one multipart request. The response returns an asset_cid and a metadata_cid, each with its own pin ID, and the metadata CID is what goes into your tokenURI. This is the docs example (not run here):

curl --location --request POST 'https://api.aiozpin.network/api/nft/' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' \
--form 'metadata=@"/sample.json"' \
--form 'file=@"/test.png"'

Two checks before you mint. First, confirm every pin reads Pinned, since the upload status guide warns that a very large directory, such as a 10K NFT drop, can sit on Pinning indefinitely while the graph is validated. Second, plan for reveal-day traffic. The public gateway allows 15 requests per minute per CID across all users and is meant for testing, while a premium gateway has no predefined rate limit. Our minting tutorial walks through the full workflow.

Frequently Asked Questions

What does a broken NFT actually look like to a collector? A placeholder image, a spinner that never resolves, or a listing with missing attributes, while the token's on-chain ownership record stays completely valid and unaffected.

Can I just fix a broken NFT's metadata link after minting? Often no. Many common ERC-721 contracts have no built-in function to change a tokenURI after mint, so there's frequently no simple way to repoint a broken reference once it's set.

Is content and link rot a real, measured problem, or just a risk specific to crypto? It's measured well beyond NFTs. Pew Research Center found 38% of webpages that existed in 2013 are no longer accessible today, the same underlying decay dynamic unpinned NFT content is subject to.

Does using IPFS for NFT metadata guarantee it stays available? No. A CID stays a valid, correctly-formed address forever, but that says nothing about whether any peer is still actually hosting the content it points to.

Why do NFT collections break months or years after mint instead of immediately? Because the underlying content is usually pinned somewhere that works fine initially, a free trial, a personal node, then quietly stops being maintained, and the content only becomes unreachable once garbage collection eventually reclaims it.

How do I actually avoid this for my own NFT project? Pin the asset and metadata together, with infrastructure built to stay online on an ongoing basis, before minting, not after. This series' minting tutorial covers the exact workflow.

Why do NFT projects need a pinning service instead of just uploading to IPFS? An upload without an ongoing pin can be removed by ordinary garbage collection. A pinning service keeps the asset and metadata pinned on nodes it runs, so the CID in your tokenURI keeps resolving.

Can an NFT's image stay online while its metadata disappears? Yes. The asset and the metadata JSON have separate CIDs, so if they are pinned separately, one pin can lapse while the other stays. Pinning both in one request avoids that.

References

We only send updates when meaningful changes ship, and you can unsubscribe anytime

Related Content

blog thumbnail

What Is a Multiaddr? Peer IDs and Addresses in IPFS

A multiaddr is a network address that names every protocol it uses, like /ip4/.../tcp/4001/p2p/ and a peer ID. Learn to read one and how IPFS peer IDs work.

7 min readNovember 06, 2026
blog thumbnail

IPFS Bootstrap Nodes and How a New Node Finds Its Peers

IPFS bootstrap nodes are the first peers a new node dials to join the Amino DHT. See how Kubo uses them, who runs them after Shipyard, and how to edit the list.

6 min readNovember 04, 2026
blog thumbnail

ipfs.io Gateway Not Working? What Changed and Who Runs It

The ipfs.io gateway now returns HTTP 429 to scripts and servers and sends browsers to inbrowser.link. See who runs the public IPFS services and what to change.

6 min readNovember 02, 2026
blog thumbnail

IPFS Glossary: Key IPFS and libp2p Terms Explained A to Z

An IPFS glossary of 115 terms from A to Z: CIDs, Bitswap, the DHT, IPNS, gateways and pinning, each defined in plain words and linked to a deeper guide.

21 min readOctober 31, 2026
blog thumbnail

What Is IPFS Provide Sweep? How Kubo Announces Many CIDs

IPFS Provide Sweep is Kubo's provider that batches CIDs by DHT region, not one lookup each. See how it works, when it became default, and how to check it.

6 min readOctober 30, 2026
blog thumbnail

IPFS Dedicated Gateway Free vs Paid Plans on AIOZ Pin

An IPFS dedicated gateway on AIOZ Pin is called a premium gateway. See what the free plan limits, what a paid plan adds, and what happens at zero balance.

6 min readOctober 28, 2026