A recipe is a file
There is no command that adds a recipe. Like loot tables and advancements, a recipe is a JSON file the world reads at load time, living at data/<namespace>/recipe/<name>.json inside a data pack. If that sentence is new, the data packs vs commands guide covers why, and the data pack generator builds the folder.
Note the folder is recipe, singular, from 1.21 onward. It was recipes before, and a file left in the old folder on a modern game is never read.
Padding: the mistake that costs the most time
A shaped recipe is matched against the smallest box that contains it, and the pattern you write is that box. Write a pattern that is three rows tall when the recipe only occupies one, and you have declared a three-row recipe.
"pattern": [
"###",
" ",
" "
]That will not craft in a 2×2 inventory grid, and in a crafting table it demands the three items sit in the top row specifically. What you almost certainly wanted was this:
"pattern": [
"###"
]Now it matches anywhere the three items sit in a row. The rule is simple: trim every empty row and column from the edges. Spaces inside the shape are meaningful and must stay — the middle slot of a ring recipe is a real, deliberate hole.
Shaped or shapeless
Shapeless throws away arrangement entirely: it takes a flat list and matches as long as those items are somewhere in the grid.
{
"type": "minecraft:crafting_shapeless",
"ingredients": [
"minecraft:paper",
"minecraft:ink_sac"
],
"result": { "id": "minecraft:written_book", "count": 1 }
}Use shapeless when the arrangement carries no meaning, which is most combination recipes. Reach for shaped when the shape is part of the idea — a pickaxe should look like a pickaxe on the grid.
Two format changes that break copied examples
Recipe JSON was rewritten twice in short order, which is why an example from a tutorial often fails for no visible reason.
| Version | Ingredient | Crafting result |
|---|---|---|
| before 1.20.5 | {"item": "minecraft:x"} | {"item": ..., "count": n} |
| 1.20.5 – 1.21.1 | {"item": "minecraft:x"} | {"id": ..., "count": n} |
| 1.21.2 and later | "minecraft:x" | {"id": ..., "count": n} |
Cooking and stonecutting results moved too: they were a bare id string before 1.20.5 and became an object afterwards. None of this changes what the recipe means, only how it is spelled, which is exactly the kind of difference that is miserable to debug by eye.
One ingredient, many items
An ingredient can be an item tag instead of a single item, written with a leading #. This is how a recipe accepts any wood:
"key": {
"#": "#minecraft:planks"
}Vanilla ships a lot of useful tags — #minecraft:planks, #minecraft:logs, #minecraft:wool — and you can define your own in data/<namespace>/tags/item/. Writing out every wood type by hand works, but it ages badly: the next update adds a wood and your recipe quietly does not accept it.
When the recipe works but the book is empty
This one confuses people because nothing is actually broken. A custom recipe is not shown in the recipe book until it is unlocked, and unlocking happens through an advancement with a recipe_unlocked reward. Vanilla does this for every one of its own recipes, which is why they appear as you gather materials.
Until you add that, the recipe still crafts perfectly if the player arranges it themselves. So if your test is "it is not in the book", try building it by hand before assuming the file is wrong.
Checklist when nothing happens
- Is the file in
recipe/, singular, on 1.21+? - Does the pattern have empty edge rows or columns?
- Does the ingredient shape match your game version?
- Did you
/reload? - Is the pack listed by
/datapack list?
Unlike loot tables, a malformed recipe usually does complain in the server log on reload, so that log is worth reading before anything else.
Where to go next
The recipe generator lays a shaped recipe out on a grid, trims the pattern for you, and rewrites the ingredient and result shape when you change the target version. From there, the loot table generator covers what comes out of chests and mobs rather than what goes into a crafting grid.