Why IPFS NFT metadata gets lost: analyzing bottlenecks
A token on-chain stores not the image itself but a pointer to it: a string like ipfs://<CID> or a regular https gateway address. As long as someone serves the content, the metadata and file open in a marketplace, wallet, and explorer.
Once serving stops, the token remains on-chain, and behind it is emptiness: holders see gray placeholders instead of avatars, write to support, and this is no longer cosmetic but broken links to the token.
The most common cause is centralized content storage. Metadata and images reside in a cloud bucket or on the project's server, while the token contains the address of that server.
A hosting change, directory rename, expired domain, or disabled instance—and the entire collection instantly turns into inaccessible collection files, and it cannot be restored from the chain.
The second bottleneck is unpinned serving. A file gets into the network as long as someone holds it, and disappears when nodes clear local copies. Content addressing does not help here: the pointer remains correct, but no one is responsible for it anymore.
Hence the loss of NFT metadata is not a blockchain failure but the absence of IPFS pinning: no one has undertaken the obligation to keep copies and monitor their availability.
We analyze how this is addressed: persistent pinning of files, replicas on independent nodes, and an upload scheme in which the address inside the token does not change when content is updated—otherwise the pointer will become broken again.
What changes after implementation: fault tolerance and speed
Before the restructuring, metadata on IPFS was served by a single node: a process crash or pinning desynchronization turned part of the collection unreadable, and serving returned an error instead of the file.
Afterward, availability rests on a coordinated set of nodes, and the client receives content in fractions of a second instead of a chain of retries and timeouts.
Serving no longer depends on a single node
Each pin is duplicated across several independent nodes, and losing a pin on one of them does not affect delivery—the coordinator sees the state of the set and re-pins what is missing.
The share of available files is calculated per collection rather than checked selectively, so a discrepancy is visible before the token holder writes about it.
The class of serving failures that used to cost the most—a single point of failure—is eliminated entirely: content is served as long as at least one node in the set is alive.
Registry volume stops growing
Duplicating pins without accounting has the opposite effect: the registry grows faster than the collection itself, and metadata versions accumulate uncontrollably.
We define a storage policy—how many copies remain per file and how many previous versions we keep available; the rest is cleaned up on a schedule.
Metadata backups are taken regularly and verified by a restore attempt, so returning the collection to a previous state is a procedure of minutes, not an analysis of what survived.
Methods for pinning NFT files: comparison of approaches
The pinning method determines whether the marketplace will see the NFT metadata a year later: if no IPFS node holds the content, the file address is valid, but there is nothing to serve at it. We examine the options chosen between at the start of a collection.
| Option | When it fits | Limitations |
|---|---|---|
| Pinning via a service | Quick launch, small collections, no in-house infrastructure | Dependence on the service's terms; availability control and backup required |
| Own pinning node | Large collections, requirement to keep data in-house | On-call duty, monitoring, and spare disk space |
| Hybrid storage | Critical metadata plus a quick start | Harder to monitor consistency of copies |
| Duplicate pinning | File loss is unacceptable | More stored volume, more failure points in the configuration |
Public gateway: serving without your own node
Serving via a gateway provides access to content at a regular address—the browser and marketplace do not need their own node. But a gateway stores nothing: it reads files from the pinning node, so if pinning is lost, the address stops serving data. A gateway is a delivery point, not storage.
Your own pinning node
Your own node gives control: you decide what is stored and for how long, and you set up serving independently of external services. The price is observability: monitoring free space, updates, and the fact that content is restored from existing copies.
Implementation stages: from content audit to handover of procedures
The work proceeds sequentially: first we record what is already pinned, then we design the pinning scheme, and only after that do we touch the production storage.
This order eliminates the situation where new pins are configured but part of the NFT metadata has already lost its provider.
Audit of tokens and files
We export contract addresses and traverse mint events, collecting tokenURI for each token. Duplicates are collapsed by checksum, broken links are marked separately—after deduplication, the volume of pins drops severalfold.
The output is a table "token / object / current pinning state" with an estimate of the scope of work.
- We design the pinning scheme: what exactly goes to IPFS—the file, JSON metadata, or both levels—and how their CIDs are linked.
- We configure pinning across several independent providers so that failure of one does not lead to loss of an object.
- We enable a background sweep: the service periodically checks the availability of each CID and repeats pinning on failure.
- We check availability through third-party gateways, not only our own—this shows the real picture for marketplaces.
- We describe the update procedure: who changes metadata, what to do when the collection changes, and how not to break immutable links.
Availability acceptance and handover
We run a sample of tokens, including rare and most recently minted ones, and record the share of objects served on the first request.
We hand over the procedures, pinning scheme, and access credentials to your team—ongoing support can then be provided by our team or your engineers.
Pinning configurations, replication schemes, and documentation
Pinning without documentation lasts until the first collection update: no one remembers on which nodes a particular CID is pinned or what will happen when the pin is revoked.
Therefore, along with replication setup, you receive a set of artifacts by which the metadata state can be reproduced without us.
- Pinning map — a table "CID → nodes, providers, retention period, owner": shows which tokens will lose availability if any node is disabled.
- Replication scheme — how many independent copies are kept, in which networks, and how a copy is added as the collection grows.
- Access policies — who can pin and unpin, where keys are stored, and what happens when the key owner leaves.
- Check log — regular sweeps: CID availability, hash match with the original file, date and person.
- File update instructions — publish the new CID, verify availability, only then switch the contract; old records remain resolvable.
- Failure response procedure — who is notified of unavailability and within what timeframe, how a copy is restored from backup.
- Release acceptance checklist — checks before issuing a batch of tokens so that broken links do not reach marketplaces.
Documentation is kept up to date: after a change in the replication scheme or rights, the pinning map and log are updated. Maintenance consists of scheduled checks per the procedure and incident analysis recorded in the same log.
Case study: how a collection stopped losing files under load
A collection of 9,800 tokens kept images and metadata on a single IPFS node with local pinning. Garbage collection triggered on every node update, some content addresses were not pinned at all—marketplaces showed gray placeholders instead of images.
Measurements before the work: 71% of files available, recovery of serving took about six hours of manual reconfiguration, and all traffic went through a single point.
We pinned each content address with several independent pinning providers (including Pinata) and on our own node, and added object storage as a cold copy.
A nightly checksum verification re-pins missing files and writes a report, while serving is distributed across four nodes in different networks with request balancing.
Numbers before and after
- share of available files: 71% → 99.8% on a sample of 2 million checks;
- serving recovery time: about 6 hours of manual work → 18 minutes automatically;
- peak serving load: one node and one gateway → four nodes, peak per node three times lower;
- errors when accessing metadata from marketplaces: 9% → 0.2%.
We separately implemented safe rollback: until the new node serves the file at the content address, traffic goes to the old one, so updating the collection does not drop availability.
A month after the migration—not a single report of missing metadata. Availability no longer depends on the state of a single server or on whether someone remembered to renew the pin.
How does pinning differ from renting a dedicated node?
On the IPFS network, metadata is available exactly as long as at least one node keeps it pinned.
Pinning is renting the very fact of storage: the provider keeps the pin on its nodes and is responsible for ensuring the content does not fall out of the network while the pin is active.
A dedicated node is renting a machine that you administer yourself: availability, updates, and disk space are entirely your responsibility.
Technically, pinning protects blocks from the garbage collector: remove it—and the file gradually disappears from the network, while the token remains with a link to nowhere.
That is why pinning is done in parallel with two or three providers rather than one: then failure of one of them does not turn the metadata into unavailable.
Your own node is justified when volume grows, metadata cannot be exposed externally, or independence from someone else's storage policy is required.
You get your own keys, your own cleanup rules, and no external quotas—but along with them, maintenance, free space monitoring, and updates are on your side.
The difference in support shows up during a failure. With renting, the provider repairs the node, while you monitor the pin term and access to keys.
With a dedicated node, we write the recovery procedure: pin checks, backups, actions in case of node loss, and we record who responds first.
The contractor's scope of responsibility: deploy a node or configure pinning, describe keys and access, set up monitoring, and hand over documentation. Key management and the decision to extend storage remain with you.
Your own machine is needed for large volumes and strict privacy requirements; for a few thousand tokens, pinning with several providers is sufficient.
Technical concerns before the start: answering point by point
Concerns before the start are usually the same: the pinning service may shut down, the metadata has already been minted, and your own node seems excessive.
Each of these concerns is addressed architecturally—through replication, an addressing scheme, and access handover—not through promises.
What happens if the pinning service shuts down?
Content addressing is not tied to the provider's domain: as long as the object is pinned on at least one node, the link from the token remains working.
We keep copies with two independent providers and on our own node, so the departure of one of them is a pinning reconfiguration, not a collection reissue.
Do I need my own node?
Your own node gives independence from others' terms and full control over pinning, but requires disk, backups, and monitoring. For medium-sized collections, we use a hybrid: a working node at the customer's site, replicas with external providers.
How to update metadata after minting?
The metadata address in a minted token cannot be changed, so we build in an indirection: the contract references an index file that contains the address of the current version. An update is publishing a new version and changing the pointer.
If immutability is more important, we issue a new revision with an explicit note in the description.
How to check availability before release?
We look not at "whether the image opens" but at availability from a cold cache: we request by content address through several independent gateways and from different networks.
Separately, we verify the metadata schema against marketplaces' expectations—field composition, types, image links.
How is support handed over?
We hand over access to the node and providers, a list of pinned objects, pinning and check scripts, and the recovery procedure from copies. The customer's engineer deploys everything from scratch using this documentation and verifies the result.
Below we have collected the remaining questions—on timelines, access, and scope of work. Describe the task, and we will come back with an estimate and a plan.Let's discuss the task: what is needed for an estimate and work plan
To make the estimate substantive rather than a rough guess, we need a set of inputs from your side. Below is the minimum list; if some data is missing, say so directly—we will collect part of it ourselves during the survey stage.
- List of collections and tokens: how many have been minted, what metadata is linked to them, and where it is hosted now—on your own node, with an external pinning service, or on regular hosting.
- Access and materials: repositories with contracts and minting scripts, pinning service accounts, keys, hosting and domain control panels, and a diagram of the current infrastructure.
- Storage state: a list of content identifiers that are currently pinned, where pinning has already been lost, and which contract links point to them.
- Availability requirements: how quickly metadata must be served to marketplaces and wallets, whether your own gateway is needed, which regions are critical, and what downtime is considered unacceptable.
- Work order and priorities: what is more important—restoring storage for already minted collections or building a process for new ones, and whether there are hard deadlines for an announcement.
- Constraints: metadata privacy requirements, who owns the keys, and who is allowed to change pinning and backup rules.
With this set, we will come back with an estimate and work plan: stages, a multi-node backup scheme, control points, and responsible parties. Describe the task—we will clarify what is missing and propose the work order.