NFT Metadata and IPFS: Where Your NFT's Image Actually Lives

Open an NFT in your wallet and you see an image, a name, maybe a list of traits. It feels like all of that lives inside the token itself. Usually it does not. What you are looking at is a small piece of data on the blockchain pointing somewhere else entirely, and where that "somewhere else" is has a real effect on whether the NFT still looks the same in five years.

What the token on chain actually stores

An ERC-721 or ERC-1155 NFT contract does not typically hold an image. It holds ownership records and, for each token, a function called tokenURI that returns a link. That link points to a JSON file, the metadata, which in turn lists a name, a description, a set of traits, and a separate link to the actual image or animation file.

So a single NFT usually involves three layers: the contract on Base, the metadata JSON, and the media file the JSON points to. Your wallet or a marketplace follows this chain every time it renders the NFT for you. If any link in that chain is broken, you get a blank box or a broken image icon instead of your NFT, even though your ownership on chain is completely unaffected.

Where that link can point

The tokenURI link can point to a few different kinds of places, and they are not equally durable.

A centralized server. Some projects host metadata and images on their own web server or a cloud storage bucket. This is simple to set up but depends on that server staying online and that company staying in business. If the project shuts down its hosting or lets a domain lapse, the link breaks and the NFT stops rendering everywhere, even though you still own the token.

IPFS. The InterPlanetary File System is a content addressed network. Instead of a link pointing to a location like a normal web address, an IPFS link (written as ipfs:// followed by a content identifier, or CID) points to a fingerprint of the file's content. Any computer that has a copy of that exact file can serve it. This is more resilient than a single server, but it comes with a catch: a file only stays available on IPFS if someone is actively storing, or "pinning," a copy of it. If every pinning service stops hosting the file, the link stops resolving even though the address itself never changes.

Arweave. Arweave is designed for one time payment, permanent storage, aiming to keep data available indefinitely without needing an ongoing pinning relationship. It trades a higher upfront cost for not depending on someone continuing to pay a hosting bill.

Fully on chain. A smaller category of NFTs stores the image data itself directly in the smart contract, often as SVG code generated by the contract. Nothing needs to be fetched from anywhere else. This is the most durable option and also the most expensive to deploy, which is why it is more common for smaller, code generated art collections than large media heavy ones.

Why your NFT sometimes looks broken

If you have ever seen an NFT show up as a gray placeholder in your wallet, a few things are usually happening:

• The underlying file was never pinned reliably, or the pinning service stopped hosting it.
• The metadata points to a centralized server that is slow, rate limiting requests, or offline.
• The marketplace or wallet you are viewing it in cached an old version of the metadata and has not refreshed it.
• The gateway used to translate an ipfs:// link into something your browser can load is temporarily overloaded. Public IPFS gateways are shared infrastructure, and heavy traffic on one project's collection can slow things down for others using the same gateway.

None of this changes who owns the token. Ownership is recorded on chain and is not affected by whether the image currently loads. But if the media layer disappears entirely and nobody has a copy, the NFT still exists as a database entry with nothing to show for it.

What to check before you treat an NFT as long term

If you are buying or minting something you intend to hold, it is worth a quick look at how the metadata is stored rather than assuming it is handled well by default.

• Look up the contract on a block explorer and check whether tokenURI returns an ipfs:// link, an ar:// (Arweave) link, or a normal https:// link to a specific company's server.
• For IPFS based projects, more established ones will often mention who pins their content, or pin it themselves, rather than relying entirely on whichever gateway happens to have cached a copy.
• Treat a plain link to a single website as the least durable option. It works fine while the project is active and paying for hosting, and stops working the moment that changes.
• Remember that even IPFS is not automatically permanent. Content addressing solves the problem of proving a file has not been altered. It does not solve the problem of someone needing to keep storing that file.

None of this is a reason to avoid NFTs, and most active collections render just fine day to day. It is simply a reminder that the picture and the token are two different things, connected by a chain of links that can be more or less durable depending on how the project set it up.