Format reference
A .build file is a small text file that Path of Exile 2 reads to load a saved Build Planner setup. Under the hood it is just JSON, which is why a single misplaced comma or wrong folder can stop it from loading.
Unofficial fan-made reference. Not affiliated with, endorsed by, or sponsored by Grinding Gear Games.
A .build file stores the data the in-game Build Planner needs to recreate a build. It is human-readable, version-controllable, and easy to share — but it is also strict about structure.
The file ends in .build instead of .json, but the content is standard JSON: key/value pairs wrapped in braces. Any tool that can read JSON can read a .build file. That also means JSON rules apply — every key needs quotes, strings need closing quotes, and trailing commas are not allowed.
The file is a plan, not your live character. Editing it does not change a character already on a realm. It is closer to a blueprint you import into the planner so you can preview or rebuild a setup.
A minimal file only needs a handful of top-level keys. A full export from a planner can contain many more, but these are the ones you will see most often.
The build label the game shows in the planner list. This is the one field you should never omit — a file with no name often looks blank or gets ignored.
Optional metadata. They make a shared file easier to recognise but do not affect whether the game loads it. Keep them short and avoid line breaks inside the string.
Optional in a starter file. Because the Build Planner format is experimental, these names can change between patches, so treat them as best-effort rather than guaranteed-stable keys.
A full export adds nested arrays for skill gems, support gems, item slots, and charms. These are the parts most likely to break after a patch, which is why re-exporting is safer than hand-editing them.
This is roughly what a starter .build file looks like. The generator produces something like it so you can test whether your folder path works before debugging a full build.
{
"name": "Lightning Sorceress Starter",
"author": "Player",
"description": "A minimal PoE2 Build Planner file",
"ascendancy": "Stormweaver"
} Save it with a .build extension and place it in your BuildPlanner folder. If the minimal file loads but a complex one does not, the problem is inside the build data, not the folder.
Most files are exported by a build-planning tool or copied from a guide, a Discord channel, or a Reddit thread. Anything that travelled through chat or a copy-paste is the most likely to arrive with broken JSON.
You can also create a minimal file from scratch. That is useful for testing your folder path or as a clean base before you import a larger build.
Path of Exile 2 is evolving, and the Build Planner file format moves with it. A file that loaded perfectly before an update can fail afterwards because a field was renamed or a gem is no longer supported.
If a file came from outside, check it locally first. The validator runs entirely in your browser and flags broken JSON and obvious missing fields.
When a patch breaks a file, re-exporting from the source planner is almost always safer than editing unfamiliar nested fields by hand.
The game only reads .build files from a specific BuildPlanner folder per platform.
Sharing a file cleanly avoids most of the JSON-corruption problems above.