Skip to main content
Run into something that does not behave the way you expect? Check the log first — Custom Advancements logs every skipped file, malformed JSON file, and missing texture through its own customadvancements logger, and names the file in question. The entries below cover the causes seen most often.
In this version, four causes account for almost every case:
  1. The root advancement has no background. This is the most common one and it is specific to Minecraft 1.18.2. A file with no parent field must have a background inside its display object, or it fails validation and is skipped with an error in the log. Add one — a vanilla texture such as minecraft:textures/gui/advancements/backgrounds/adventure.png works without any extra files. See Backgrounds.
  2. A missing display or criteria object. Both are required at the top level of every advancement file.
  3. Malformed JSON. A missing comma or brace stops that single file from loading; look in the log for a parse error naming the file. The rest of your advancements still load and the game does not crash.
  4. You haven’t reloaded. Files added while the world is already loaded need a /ca reload or a restart before they are picked up.
[INSERT IMAGE: A log excerpt showing the “does not match the required ‘.json’ format!” error next to a correctly loading file, for comparison]
Check these in order:
  • The resource location is wrong. A file at customadvancements/data/textures/my_background.png is referenced as customadvancements:textures/my_background.png. Both the textures/ segment and the .png extension are part of the location — leaving either out is the usual mistake.
  • The file extension is not supported. See Textures for the full list the loader accepts. Anything else is skipped with a warning.
  • The background is on a child advancement. Backgrounds only render on root advancements — those with no parent field. On a child the field is simply ignored.
  • The player does not have the file. Custom Advancements 4.7.5 does not send textures over the network. Every client reads them from its own customadvancements/data/textures/ folder, so a player without the mod, or without the image, sees the vanilla default.
The mod logs a warning naming both the advancement and the texture location it failed to find, which is the quickest way to confirm which of these applies.
[INSERT IMAGE: An advancement tab background rendering as the purple-and-black missing-texture checkerboard]
By default the background texture is tiled across the panel in 16×16 pixel steps, exactly as vanilla renders its own backgrounds. That is correct for seamless tile patterns and wrong for a screenshot or piece of artwork.To draw the image once, filling the panel:
  • Set "largeBackground": true in the display block. Without it, the next two fields do nothing.
  • Set "shouldBgClip": true to preserve the image’s proportions instead of stretching it.
  • Set "bgRatio" to the image’s real width divided by its real height — for example 1.7777 for a 1920×1080 image.
A stretched, distorted image almost always means shouldBgClip is missing; a wrongly cropped one means bgRatio does not match the file. See Backgrounds.
A title rendering as customadvancements.advancements.my_root.title means Minecraft found no translation for that key in the active locale.
  • Check for a typo. The key in the advancement JSON must match the key in the language file character for character.
  • Check the file name and location. Language files go in customadvancements/data/lang/ and are named with a Minecraft locale code, such as en_us.json. Only .json files are read.
  • Ship an en_us.json. English is Minecraft’s fallback locale, so a complete English file prevents raw keys from ever showing.
  • Check that the player has the files. Language files are not sent over the network in this version — each client reads them from its own customadvancements/data/lang/ folder. If a title looks right for you and raw for someone else, that is the cause.
See Language Files.
/ca reload does not re-read config/customadvancements-common.toml. It reloads advancement JSON files, textures, and language files only.Edit the config while the game or server is stopped, then restart to apply it. This applies to every option: blacklists, progression settings, tab sorting, and the rest. See Config File.
  • Check the exact resource location. Entries in advancementsBlacklist must match namespace:path exactly, including case. IDs are validated as resource locations when the config loads — but at that point the server is not running yet, so an ID that simply does not exist is accepted and then silently does nothing. Verify yours against /ca generate resource_locations output.
  • Wildcards are not supported in this version. "create:*" does not mean “every Create advancement” — it matches nothing. To remove a whole mod’s tree, blacklist that mod’s root advancement and let the cascade remove its children.
  • Removing a child does not remove its parent or siblings. The cascade runs downward only. To remove an entire tab, blacklist its root advancement.
  • In whitelist mode, ancestors are kept automatically. If something unexpected survives with blacklistIsWhitelist = true, it is most likely a required ancestor of an advancement you did list — parents are always preserved so the tree does not break.
  • Restart after editing. Blacklist changes are config changes, so they need a restart.
See Blacklist & Whitelist.
  • Confirm advancementProgression = true is actually set in config/customadvancements-common.toml — the progression system is off by default — and that you restarted afterwards.
  • Check advancementProgressionMode. Under MINECRAFT or CUSTOM_ADVANCEMENTS, advancements outside that namespace are never gated, which looks like the system “isn’t working” if you happen to be testing with a mod advancement.
  • Under MODS mode with an empty modBlacklist, every namespace is gated — including minecraft. If you expected vanilla advancements to stay ungated, add "minecraft" to modBlacklist.
  • Root advancements have no parent to gate them, so they are always immediately earnable. Use connectedAdvancementsList to give a root a virtual prerequisite from another tree.
  • Check the arrow spacing in connectedAdvancementsList. Entries must be written "parent -> child" with a space on each side of the arrow; "parent->child" is parsed incorrectly and matches nothing.
  • Recipe advancements are never gated, in any mode.
  • A gated advancement that cannot be earned yet shows no error to the player — the criteria are simply not granted. That is expected behavior, not a bug.
See Progression.
Override files fully replace the original advancement — they are not merged with it field by field. Whatever your file contains becomes the entire definition, so any field you left out is gone from the advancement.The fix is to start from a complete definition rather than writing one by hand: run /ca generate advancement <id> to export the original, then edit the exported file in place, changing only what you mean to change. See Blacklist & Whitelist for the full override workflow.
/ca generate advancement <id> refuses to export an advancement whose namespace is customadvancements, and reports The file for <id> already exist!. Those advancements come from your own customadvancements/customadvancements/ folder — the file already exists on disk and is yours to edit directly, so there is nothing to generate.If you meant to export a vanilla or mod advancement, double-check the ID you passed. See Commands.
  • advancementSortingList only has an effect when advancementTabSortingMode = "DEFINED_LIST". Under UNSORTED or ALPHABETICALLY the list is ignored entirely.
  • Entries must be the root advancement’s resource location — not a child advancement, and not the tab’s display name. Use /ca generate resource_locations and look for the IDs ending in /root, or check which of your files have no "parent" field.
  • Tab sorting is a config setting, so it needs a restart to apply — /ca reload will not pick it up.
See Tab Sorting.
That command exports every loaded advancement into your customadvancements/ folder, and every exported file then overrides the advancement it came from. If something looks wrong afterwards, an edited or partially deleted export is usually the cause.Delete the files you did not intend to keep. Anything removed from customadvancements/<namespace>/ reverts to the game’s own version on the next reload.A related case: if you also set disableStandardAdvancementLoad = true, any advancement in your folder whose parent is not present in the folder is dropped along with all of its children. Either export the missing parents too, or turn that option off. See Blacklist & Whitelist.
Still stuck? The FAQ covers what the mod can and cannot do in this version, which sometimes turns out to be the real answer.