NFT metadata and media: understand URLs, IPFS and availability

Follow the complete reference chain

Start with an asset account, read its URI and retrieve the metadata document. Then read the image, animation or other media fields and fetch those resources. A failure can occur at any link.

Choose a teaching asset Signal #17. Its account points to metadata JSON M. M names image I and a separate animation A. Retaining M alone does not prove that I and A remain available.

Some metadata or attributes can live onchain under the asset's standard. Determine which fields the wallet actually reads. A cached marketplace thumbnail may be another copy with another update schedule.

Document the URI scheme and each dependency. A generic statement that an NFT is on the blockchain does not describe where its image bytes live.

An ordinary web URL identifies a retrieval location

An HTTPS URI asks a host for content at a path. The operator can serve new bytes at that location or stop serving it, subject to its architecture and controls.

If Signal #17 points to an ordinary JSON URL, that JSON can change without the onchain URI changing. An onchain update authority may separately be able to replace the URI itself.

These are two distinct mutability questions: can the pointer change, and can the content returned by the pointer change? Inspect both before describing metadata as immutable.

Redirects, certificates, host outages and access restrictions can affect retrieval even when the asset record remains valid.

A content identifier establishes identity rather than a host

IPFS content identifiers address content using cryptographic and format information. With the same content and import settings, nodes can derive the same identity. Changing the addressed content changes that identity under the addressing model.

A CID is not simply interchangeable with the ordinary SHA-256 checksum of the original file. IPFS can split files into blocks and represent them through a content-addressed structure.

If metadata M is addressed by CID, changing its bytes requires a different addressed content identity. But an authority may still change the asset's pointer from M to a new document.

Content identity also does not ensure availability. Someone must retain and serve the relevant blocks so retrieval can succeed.

Content identity and retention are different questions

Read the actual retention commitment

Pinning tells an IPFS node to retain content rather than discard it through ordinary local garbage collection. Availability still depends on that node or other retaining peers being reachable and maintaining the data.

A hosted pinning service has its own billing, retention and access conditions. Multiple independent copies and an operational retrieval plan address another part of the problem.

When a project promises long-term storage, inspect the specific network, funding and service arrangement. Do not treat the word permanent as a substitute for that mechanism.

Preserve all referenced resources, not just the top-level JSON. A retained metadata file pointing to an expired image URL still produces a broken image.

Locate a missing image step by step

First verify that the asset account exists and decode its current URI. If that fails, investigate cluster, account identity, source coverage and decoder support.

Next fetch the metadata. Check response status, content type, valid JSON and expected schema. Then inspect and fetch the image URI itself.

If the content is addressed through IPFS, distinguish a failing gateway from content unavailable across the retrieval path. Try an appropriate alternate retrieval route without claiming that one successful gateway proves future retention.

Finally compare the wallet's cached presentation with current references. A stale cache and a lost media file require different fixes. Neither necessarily changes current onchain ownership.

Publish a dependency record with a new asset

Record onchain address, standard, current URI, update authority, media references, content identities and retention responsibility. Include licence terms separately from file hosting.

Test retrieval through the actual wallets and applications you support. Check file types and reasonable sizes, not just whether a browser can open one URL.

For updates, preserve the prior version and explain which authority can make future changes. A useful publication record makes identity, mutability and availability inspectable.

Common questions