Compatibility

Use this page when installing an optional integration, running a multiplayer server, migrating a pre-port test configuration, or troubleshooting rules that do not apply as expected.

Supported versions and loaders

Minecraft	Loaders
1.20.1	Forge, Fabric
1.21.1	NeoForge, Fabric
26.1.x	NeoForge, Fabric
26.2	NeoForge, Fabric

Fabric builds require Fabric API. Jade is optional on every supported loader.

Multiplayer sync

The server resolves configuration against its current item, block, and tag registries. It sends the resolved rules to clients that have Better Harvest Levels installed when they join, after /bhl reload, and after a data-pack reload.

Client sync keeps harvest prediction and Jade output aligned with the server’s harvest enforcement. A client without Better Harvest Levels does not receive these rules, but the server still decides whether breaking a block produces drops.

Note

When a client display disagrees with the server after a configuration edit, run /bhl reload and check that the client also has Better Harvest Levels installed. For tag changes from a data pack, complete a data-pack reload so the server re-resolves those tags and sends the updated rules.

Jade support

Jade is an optional integration. On blocks with a Better Harvest Levels override, the mod can supply the changed required-tool icon and harvestability result. A custom tier uses its iconItem as the fallback icon when there is no matching vanilla tool icon. The reserved hand tier has no required-tool icon.

Jade version caveats

• Fabric 26.2 must use Jade 26.2.8+fabric or older. Jade 26.2.9+fabric rewrote the harvest tool API and is declared incompatible by the mod.
• On Forge 1.20.1, Jade’s harvestability checkmark follows vanilla for changed block requirements. The required-tool icon and actual harvest enforcement remain correct.

If Jade shows stale information on another supported combination, reload the Better Harvest Levels configuration, confirm both server and client use the intended files, and use /bhl check to inspect the server’s active result.

Modded tool behavior

A tool component does not guarantee a recognized tier

A modded item can have a minecraft:tool component without being a recognized vanilla tiered tool. Better Harvest Levels cannot derive a tier for that item, so block overrides defer to vanilla unless the item has an explicit tools.json override.

To fix it:

1. Find the item’s registry ID.
2. Add an exact item rule under tools.json, assigning a known tier.
3. Run /bhl reload.
4. Hold the item and use /bhl check hand, then target the block and use /bhl check.

The single-item tool example shows the required file shape.

Plain items are treated as hand

An item without a tool component is treated as hand. If a plain item should act as a tiered tool, add a tools.json override for it, reload, and verify its resolved tier with /bhl check hand. The override assigns a tier, but the block’s vanilla tool category still applies where one exists.

Swords on 26.x defer to vanilla

On 26.x, swords have no deniesDrops rule. A block override therefore defers to vanilla for a sword unless that sword receives a tool tier override.

Add an exact or tag-based tools.json rule for the affected sword, run /bhl reload, and test the sword against the targeted block with /bhl check. Use the tool selector reference when one rule should cover several swords.

Migrating a pre-port 2.0 test configuration

A tiers.json file from a pre-port 2.0 test build does not contain the copper tier. Keep the existing file and add this object to its tiers array:

{
  "name": "copper",
  "level": 2,
  "displayName": "Copper",
  "color": "#E77C56",
  "builtIn": true,
  "iconItem": "minecraft:copper_ingot"
}

Save the file, run /bhl reload, then use /bhl info to confirm that copper appears between stone and iron. Use /bhl check on any rules that require copper.

Caution

Do not delete only tiers.json expecting it to regenerate. Better Harvest Levels 2.0.0 writes default files only when the entire config/betterharvestlevel/ directory is absent. Do not delete that directory, because it also contains the block, tool, and equivalence configuration.

Invalid configuration

Inspect the game or server log first when a rule is missing after startup or /bhl reload. Better Harvest Levels skips invalid files or entries instead of applying a partial guess:

• Invalid JSON causes the entire affected file to be logged and skipped. Fix the JSON syntax, reload, and check the loaded rule counts reported by /bhl reload.
• An unknown selector type is logged and skipped. A malformed tag selector or an exact item or block ID that is not in the current registry resolves no targets. Compare the selector with the supported syntax, then reload.
• An invalid regular expression is logged and skipped. Correct the expression and remember that it must match the complete registry ID.
• An unknown tier name causes the affected block or tool override to be logged and dropped during reload. Unknown tiers cannot satisfy requirements. Define the tier in tiers.json, correct the misspelling, or replace it with a known tier before reloading.

After correcting an error, use /bhl reload, confirm the reported tier and rule counts, then run /bhl check hand, /bhl check block, or /bhl check on the affected item and block. The invalid entry reference lists the validation rules, and the Commands guide explains each inspection command.

Related guides

• Configuration documents every file, selector, and tier field.
• Examples provides complete block, tool, tier, and equivalence files.
• Commands covers reload and active-rule inspection.