
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:
tokenURI after minting, so there's often no "just fix the link" option once the underlying content goes offlineUpdated Oct 22, 2026: merged our separate post Why NFT Projects Need a Pinning Service, Not Just IPFS into this guide.
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.
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 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.
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.
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.
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.
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.

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.

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.

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.

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.

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.

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.