NFT Metadata Explained: What Frozen Means and When to Refresh

2026-09-03

Your token still shows a placeholder three days after the reveal. A collection you hold suddenly displays different traits than it did last week. Neither of those is about the token. Both are about one string held by the contract and what sits at the other end of it, and frozen and refresh are the two words for what can and cannot happen to that string.

NFT Metadata Explained: What Frozen Means and When to Refresh: key points at a glance

What the token holds and what it does not

An NFT is an id that a smart contract records against an owner address. The name, the description, and the artwork are not in that record.

The ERC-721 token standard puts them behind a single function. Given a token id, tokenURI returns a Uniform Resource Identifier, and the specification adds that the URI may point to a JSON file that conforms to the ERC721 Metadata JSON Schema.

That schema is three properties long: name identifies the asset the NFT represents, description describes it, and image is a URI pointing at a resource with an image mime type. The artwork is therefore a second hop. The contract points at a document, and the document points at a file.

Beyond the id and the owner, what an application shows you is read from that document rather than from the chain. The part everyone looks at is the part the chain does not hold.

Where the pointer leads decides what can change

A token URI is a string, and it can be several different kinds of thing. It can be a web address on a server someone operates. It can be an IPFS address built around a content identifier. It can carry the whole document inline, so that nothing is fetched at all.

The distinction matters because of what each one is able to become. A web address names a location, not content: whoever runs that server can return different bytes tomorrow at the same address, and nothing on the chain changes when they do. A content identifier behaves differently. The IPFS documentation states that CIDs are based on the content's cryptographic hash, and that any difference in the content will produce a different CID. A CID cannot resolve to edited content, because edited content is a different CID and needs a different pointer.

An inline document goes one step further, since there is no fetch left to intercept. It costs size, because every byte sits in contract storage.

Where the token URI points	Can the far end serve different content later	What has to change for the artwork to change
A web address on someone else's server	Yes	Nothing on chain
An IPFS content identifier	No	The contract has to return a different URI
The document encoded in the URI itself	No	The contract has to return a different URI

What frozen metadata actually means

Frozen is a claim about two locks, and it holds only when both are shut. The first is on the far end: the content behind the pointer cannot be swapped for other content. The second is on the pointer: the contract cannot be made to hand back a different URI.

A collection can put every file on IPFS, publish the content identifiers, and still keep a function that lets the deployer set a new base URI. Content addressing shuts the first lock and leaves the second one open. A collection of 10,000 tokens can be served from a single base URI, in which case one owner transaction changes what every id in it resolves to.

So frozen reads the way the owner privileges on any other contract read. The question is not what the contract does today. It is what the holder of the owner key is still able to make it do.

Why what you see is a cached copy

Marketplaces and wallets do not call tokenURI and fetch a document every time you scroll. They read it once, keep their own copy of the JSON, download the image, and serve you that copy, because rendering a gallery any other way would mean one outbound fetch per tile against servers the site does not control.

There are therefore three copies of the answer, and they can disagree: what the contract returns now, what the document at that URI says now, and what the indexer wrote down last time it looked. A wrong display is a statement about the third copy, not evidence that the first two are wrong.

ERC-4906 exists because of that gap. Titled EIP-721 Metadata Update Extension, it adds a MetadataUpdate event so that, in its own words, the third-party platforms such as NFT market could timely update the images and related attributes of the NFT, with a BatchMetadataUpdate event covering a range of ids in one emission. Its stated motivation is that contracts were already emitting their own events for this, and that building an individualized solution for each collection was extra effort for the platforms reading them.

What a refresh actually does

A refresh is an instruction to the indexer, not to the chain. It tells the platform to throw away what it wrote down and do the whole read again: call tokenURI, fetch whatever comes back, parse it, and re-download the file named in the image field. Nothing is signed, no fee is paid, and the contract is not touched.

That is why a refresh helps in one situation only, which is that the stored copy is behind the current answer. If the contract now returns a new URI, or the document at the old URI now holds different bytes, a refresh brings the display into line. If neither is true, it replaces the stored copy with an identical one.

A refresh is the manual version of what ERC-4906 automates: where a collection emits the update event, an indexer watching for it redoes the read unasked.

When a refresh will not help

The useful question is not whether to refresh but which failure you are looking at, because unrelated ones present the same way: the picture is wrong, or missing.

What you see	What is going on underneath	Does a refresh change it
Placeholder art after a reveal	The contract still returns the pre-reveal URI	Not until the contract returns the new one
Broken image, document still loads	The image URI is dead or unreachable	No, the fix is at the host
Nothing loads at all	The metadata document is unreachable	No
Traits differ from the document	The stored copy is stale	Yes
Right artwork, wrong collection page	You are looking at a different contract	No

The dead-pointer rows are the ones read as a platform bug. If the token URI is a web address, the server behind it can be switched off, and the pointer keeps pointing at nothing. If it is a content identifier, the same outcome arrives by a different road: the IPFS documentation states that while IPFS guarantees that any content on the network is discoverable, it doesn't guarantee that any content is persistently available, and that data can be pinned to one or more IPFS nodes so that it is not deleted during garbage collection. A CID that no node holds is a valid and permanent name for nothing.

What to check before you ask for a refresh

Three reads separate these cases, and none of them needs the marketplace to be working.

Read the contract first. On a block explorer, open the collection's contract and call tokenURI with your token id. The string that comes back is the on-chain answer, and it is the only one of the three copies the chain attests to.

Then open what it returned. Fetch that URI and read the JSON. If name, description, and image hold what you expect, the chain side is right and the problem is downstream of it. If the URI does not load, no refresh will produce a document that is not there.

Then follow the image field, because a document can be intact while the file it names is gone, at a different host from the one serving the metadata. When all three reads are correct and the marketplace still shows something else, that is the refresh case, and it is the only one.

The bottom line

Metadata is a document the chain points at, not a thing the chain holds. Frozen means both locks are shut: the far end cannot serve different content, and the contract cannot be made to point somewhere else. One lock without the other is not frozen, and content addressing on its own only shuts the first.

A refresh touches none of that. It re-reads the pointer and the document and overwrites a cached copy, so it repairs one failure only: a display that has fallen behind. Read tokenURI, open what it returns, follow the image field. Those three reads separate an indexer that needs to look again from a pointer with nothing left at the end of it. To keep learning the fundamentals, follow more from Bitbase Academy.