Fix "Couldn't load tag ... as it is missing following references"
A tag is a JSON list of ids. When one of them doesn’t exist, the whole tag fails to load. On a NeoForge 1.21.1 server,
an item tag examplemod:gems that listed examplemod:rubby logged:
[Worker-Main-1/ERROR] [minecraft/TagLoader]: Couldn't load tag examplemod:gems as it is missing following references: examplemod:rubby (from mod/examplemod)Each line under it is an id the game couldn’t find, followed by the data pack or mod it came from. The game doesn’t stop, so the error is easy to miss: the server started normally after it. Other content that uses the tag (recipes, tools that need it) then stops working.
Checked on 19 November 2026 on a NeoForge 1.21.1 server.
Common causes
Section titled “Common causes”- A typo in the id, or the wrong namespace (
minecraft:rubyinstead ofexamplemod:ruby). - An entry from another mod that isn’t installed.
- An id renamed between Minecraft versions, after a port.
Correct the id. For an entry from a mod that may not be installed, mark it optional, as in NeoForge’s documentation (NeoForge: tags):
{ "values": [ "examplemod:ruby", { "id": "othermod:sapphire", "required": false } ]}A plain string is the same as "required": true.
The tag doesn’t load at all
Section titled “The tag doesn’t load at all”If there is no error but the tag is empty, check the folder. Since Minecraft 1.21 the folders are singular:
data/<namespace>/tags/block/ and tags/item/, not tags/blocks/ and tags/items/. A tag in the old folder is
ignored.
In Linen
Section titled “In Linen”Crash Doctor in Linen reads the crash report and the log next to it, then names the mod, the line and what to change. It’s free. The item tag and block tags with datagen how-tos show a tag that loads.