Config Reconciler
If you have ever maintained a modpack, you know the pain of updating configuration files. You ship a new default, and suddenly every player's carefully tuned settings are wiped out. Or worse, you keep the old defaults, and new mod features remain broken because their required settings are missing. Config Reconciler solves this dilemma with a conservative, key-level merging approach that respects both the modpack author's intent and the player's independent choices.
Why Configuration Merging Matters
Most modpacks handle config updates by simply overwriting files. That works for a fresh install, but it is a nightmare for updates. Players lose their keybinds, their video settings, their preferred mod toggles. Config Reconciler for Minecraft takes a different path. It compares three states: the previous pack default, the player's current configuration, and the incoming pack default. Independent changes made by the player are combined with the new defaults. When a conflict occurs on the same key, the player's value wins by default, and the conflict is recorded for later review.
Key-Level Merging for Common Formats
This mod does not just copy files. It performs conservative key-level merging for JSON objects, Java .properties files, and a subset of TOML. That means if a mod adds a new option in an update, your players get that new option with its default value, while their existing tweaks remain untouched. Unsupported divergent files are left alone, keeping the player's copy intact. This is a huge quality-of-life improvement for any pack author.
Features That Save Time and Headaches
- Backups: Automatic backups are created before any merge, so you can always restore a previous state.
- Reports: Text and JSON reports show exactly what changed and what conflicts were found.
- Dry-Run Mode: Preview updates without applying them, perfect for testing a pack update on a copy first.
- No Telemetry: The mod performs no network access or telemetry. Your players' data stays local.
For players using a launcher with a built-in add-on catalog, such as the foxygame.net launcher, installing Config Reconciler is a one-click process that also handles version compatibility checks, so you can spend less time fiddling with JAR files and more time playing.
Supported Minecraft Versions and Loaders
Config Reconciler supports a wide range of Minecraft versions across three major loaders. Separate downloads are available for Fabric, Forge, and NeoForge. You must install one JAR matching your loader in the mods/ folder.
Fabric and Forge Compatibility
For Fabric, the supported versions include 1.18.2, 1.19.2, 1.19.4, 1.20.1, 1.20.4, 1.20.6, 1.21.1, 1.21.4, 1.21.5, 1.21.8, 1.21.10, 1.21.11, and the newer 26.1.2 and 26.2. Fabric API is not required, but Fabric Loader 0.16.14 or newer is necessary. Forge users get support for 1.18.2, 1.19.2, 1.19.4, 1.20.1, and 1.20.4. NeoForge covers 1.20.6 through 1.21.11 plus the 26.x versions.
Java Version Requirements
Use the Java version required by the game. Java 17 is needed for the older versions, Java 21 for 1.20.6 through 1.21.11, and Java 25 for the 26.x releases. Other patches, snapshots, 1.12.2, 1.16.5, and Quilt are not advertised in this release.
How to Install Config Reconciler
To download Config Reconciler, head to the official project page and grab the JAR that matches your loader. Installation is straightforward. Drop the JAR into your mods/ folder, then launch the game once to generate the default settings. The mod alone has no effect until a modpack supplies managed defaults, so do not worry about it breaking anything out of the box.
Setting Up Managed Defaults
The important setup rule is to place your default files in config/config_reconciler/defaults/ using paths relative to config/. For example, a file at config/config_reconciler/defaults/example.json manages config/example.json. Do not ship a managed target through normal launcher overrides, because the launcher would overwrite the player's copy before Minecraft starts. Ship that file only under the defaults folder and let Config Reconciler update its target.
Migrating an Existing Pack
When migrating an existing pack, first ship its current defaults. Differing existing targets are adopted on the first run. In later pack releases, update the defaults and optionally the config/config_reconciler/pack-version.txt file. Settings are generated in config/config_reconciler/reconciler.json. Set dryRun to true to preview updates. The default conflict policy is KEEP_USER, but KEEP_INCOMING is also available. Reports are located in .config-reconciler/reports/latest.txt and latest.json.
Alpha Limitations to Know
This is an alpha release. Dedicated-server bootstrap and two-launch merge checks do not cover full gameplay or client GUI behavior. Always test a pack update on a copy first. The mod manages config/, not options.txt or per-world serverconfig/. JSON arrays are treated as atomic values, and TOML arrays of tables and multiline strings are not merged when both sides differ. This is not a complete TOML parser. Divergent files above the merge-size limit remain unchanged without large backup triplets.
There is no in-game conflict editor, popup, or automatic restore. Restore manually from backups with the game closed. Writes are atomic per file, not a transaction across all configurations. Conflicts are reported during the update that detects them, and historical reports remain available after later runs. A restart is recommended after files change because another early-loading mod may already have cached them. Also, reports and backups can contain secrets from configuration files, so review them before sharing.
License and Final Thoughts
Config Reconciler is released under the MIT License. Runtime loader and library APIs are acknowledged in META-INF/THIRD_PARTY_NOTICES.md, but their implementations and Minecraft game files are not included in the JARs. Source code is supplied separately. The project was developed with AI assistance, and the avatar is an AI-generated symbolic illustration of configuration merging, not an in-game screenshot. This is an independent community project, not an official Mojang, Microsoft, or CurseForge product.
For modpack authors tired of config-related support tickets, Config Reconciler is a breath of fresh air. It respects your players' choices while keeping your pack up to date. Download Config Reconciler today and say goodbye to the old overwrite-and-pray workflow. The foxygame.net launcher also integrates this add-on into its catalog, giving you automatic updates and version matching for a smoother experience.