Common NFT Metadata Errors and How to Fix Them Before Minting
Metadata problems are one of the most common reasons a collection looks broken on marketplaces after minting — missing images, garbled trait names, or rarity rankings that don't display. Almost all of these are catchable before you mint. Here's what to check.
01 — Broken or Unresolved Image Links
The single most common issue: metadata pointing to an image URI that doesn't resolve. This usually happens when files are uploaded to IPFS or Arweave after the metadata JSON was generated, so the CID in each file's image field is placeholder text or references the wrong location.
How to fix it:
- Upload your images first and get your final CID before generating or exporting metadata
- Double-check the URI format matches your storage provider —
ipfs://CID/1.pngfor IPFS, or the correct Arweave transaction path - Spot-check a handful of metadata files against a gateway link (e.g. ipfs.io) before minting to confirm images actually load
Key point: Always upload assets first, generate or update the CID second, and mint third. Doing this out of order is the root cause of most broken-image collections.
02 — Mismatched Token ID and File Naming
Metadata files and image files need to reference each other by a consistent, sequential ID — typically starting at 0 or 1 depending on your standard. A mismatch (file 47.png pointing to metadata for token 46) causes wrong images to display against the wrong trait data.
This most often happens after manual edits to a collection — renumbering a batch of files by hand, or removing a token post-generation without updating every reference that follows it.
Fix: Avoid manual renaming wherever possible. If you do need to remove or reorder tokens, regenerate the full metadata set rather than patching individual files — a single off-by-one error cascades through the rest of the collection.
03 — Inconsistent Trait Naming
Marketplaces group NFTs by exact trait value matches. If "Red" and "red" — or "Gold Chain" and "Gold chain" — appear as separate values due to inconsistent capitalisation or spacing, your rarity rankings and trait filters will split incorrectly, making genuinely common traits appear artificially rare.
| Problem | Example | Fix |
|---|---|---|
| Capitalisation mismatch | "Blue" vs "blue" | Standardise casing across all layer/file names before generating |
| Trailing whitespace | "Gold Chain " vs "Gold Chain" | Trim file names before upload |
| Inconsistent naming | "Hat" vs "Hats" as layer/attribute name | Lock attribute (trait_type) names early and don't change mid-project |
04 — Missing or Incorrect Attribute Types
Numeric traits — like a "power level" or "boost %" — need to be typed correctly in metadata (as display_type: "number" or "boost_percentage") rather than as plain strings, or marketplaces won't render them as rankable numeric stats.
Similarly, every token should have the same set of attribute keys even if a specific trait is absent — represented as "None" rather than omitted entirely. Omitting the key altogether can break rarity calculation tools that expect every token to report on every trait category.
Generate Clean, Consistent Metadata Automatically
Standardised trait naming, consistent attribute keys, and correctly typed fields — generated automatically from your layers.
Start Generating →05 — Duplicate Token IDs or Duplicate Combinations
Two failure modes fall under "duplicates": identical trait combinations appearing on two different tokens, and metadata files accidentally sharing the same token ID. Both are usually the result of manual edits after generation, or a generator that didn't properly track combination history during a large run.
Before minting, verify:
- Run a duplicate-combination check across your full metadata set
- Confirm token IDs are sequential with no gaps or repeats
- If you removed any tokens post-generation, re-verify the full set rather than assuming the rest is unaffected
06 — Incorrect Royalty or Creator Fields
On Solana specifically, the creators array must sum to exactly 100% share and be verified on-chain, or marketplaces may show royalties as unverified. On Ethereum-standard collections, royalty fields vary by marketplace (some read from the contract, others from metadata), so check your target marketplace's current requirements rather than assuming one field works everywhere.
Frequently Asked Questions
Why don't my NFT images show up on OpenSea or Magic Eden after minting?
This is almost always a broken image URI — metadata pointing to a CID or path that doesn't resolve. Upload your assets to IPFS or Arweave first, confirm the final CID, and only then generate or finalise your metadata.
Can I fix metadata errors after minting?
It depends on whether your metadata is mutable or frozen on-chain. Many standards allow an update authority to correct metadata post-mint, but this varies by chain and contract — it's far simpler to catch errors before minting than rely on being able to fix them after.
Why are my rarity rankings wrong on marketplaces?
Usually inconsistent trait naming — the same trait appearing under slightly different capitalisation or spacing gets counted as separate values, skewing rarity percentages. Standardise naming before generating metadata.
How do I check for duplicate NFTs before minting?
Run a duplicate-combination check across your full metadata set before upload. A good generator does this automatically during generation, flagging any repeated trait combinations rather than letting you discover them post-mint.
Catch Errors Before They're Permanent
Once a collection is minted, metadata errors are far harder — sometimes impossible — to fix cleanly. The fix is almost always the same: upload assets first, generate metadata second, verify consistency third, and only then mint.
TheMintLab's generator and metadata tool handle naming consistency, attribute formatting, and duplicate checks automatically — free, in your browser.