Reading NFT Metadata Fields Without Guesswork
When a collector reports that your NFT shows a blank image, the problem is almost always in the metadata JSON or the URI that points to it — not in the mint transaction itself. This guide walks through the fields you should verify before mainnet.
The name and symbol fields
The name field is what wallets and marketplaces display as the token title. It can differ from the on-chain name stored in the token metadata account — marketplaces typically prefer the JSON value fetched from the URI. Keep names under 32 characters if you want consistent display across older wallets.
The symbol field is often ignored by modern marketplaces but still appears in block explorers. A short uppercase symbol matching your collection branding prevents confusion when traders search by ticker-like strings.
description and external_url
Description text supports plain paragraphs in most marketplaces. Avoid embedding HTML unless you have tested the specific marketplace renderer. The external_url should link to a page you control — a project site or artist portfolio — not a temporary file host.
image and animation_url
The image field must resolve to a direct media file or a gateway that returns one. Common failures: linking to an HTML gallery page instead of the PNG, using IPFS gateways that rate-limit, or pointing to thumbnails when collectors expect full resolution.
If you use animation_url for video or interactive work, confirm the MIME type loads correctly in at least two wallets your audience uses.
attributes array
Each trait is an object with trait_type and value. Spelling matters — "Background" and "background" are separate traits in most indexers. Empty strings and null values sometimes render as broken trait chips.
For generative collections, verify that every possible combination in your generation script appears in at least one sample JSON file you test.
properties.files
Some standards include a properties.files array listing URIs and types. Not all marketplaces read it, but portfolio sites and exhibition tools sometimes do. Include it when you want a canonical list of all assets attached to a token.
On-chain vs off-chain mismatch
The URI stored on-chain is the source of truth for where to fetch JSON. If you update JSON at the same URL after mint, collectors see the new content — which may or may not be what you intend. Immutable storage (Arweave with permanent IDs) avoids accidental overwrites.
Quick verification routine
- Fetch the on-chain URI from an explorer and download the JSON manually.
- Open each media URL in a private browser window.
- Compare traits across five random token IDs.
- Check creator shares total 100 and addresses match your wallet.
Need a second pair of eyes? Our metadata review session runs this checklist against your actual files.