FAQ

FAQ and Known Limitations

简体中文 | English

← Back to the index

This page is written for server owners. The first half answers the questions that come up most often ("the mob just stands there"), the second half lists the limitations that still exist in this release. Every error message, config key and number below is taken from the plugin manual, so you can act on it directly.

Tool	What it tells you
/mobinteract status	World filter, mob filter, mining and placement parameters, spawn-equipment chance, known mob count, mobs currently mining, temporary block count, BlockLocker integration state
/mobinteract inspect	For the mob within 16 blocks of your crosshair: cooldowns, placements used in the current chase, main-hand pickaxe, most recent behaviour, backpack contents
debug: true in mining.yml	Prints the accept/reject reason for every candidate block and the renewal decision when a temporary block expires; it floods the log, so turn it off afterwards

1. Not enabled: red in /plugins

Symptoms

• MobInteract shows up red in /plugins and stays disabled;
• The startup log contains [ModernPluginLoadingStrategy] Could not load plugin ... InvalidPluginException: Unsupported API version 26.3;
• Loading it afterwards with PlugMan reports That file is not a valid plugin or Plugin didn't load any plugin providers?.

Cause

The server validates api-version during the startup plugin scan, and an api-version newer than the server is rejected outright — the plugin never reaches the loading stage. Any plugin that "loads it later" cannot fix that. This is the wrong jar for your server, not a permission or dependency problem.

What to do

1. Use a jar made for older servers: the jar published for general use is made for the oldest supported version, 1.21.8, so one jar loads on 1.21.8 ~ 26.x;
2. Only a jar made specifically for 26.3 requires server 26.3 or newer — if your server is 26.2 or similar and you installed that one, this is exactly the error you get;
3. The minimum supported version is 1.21.8; older servers lack the pathfinding and scheduling interfaces this plugin uses;
4. Restart the server fully after swapping the jar (a reload is not enough), then confirm the colour in /plugins and that /mobinteract status answers.

2. The mob stands still: start with this table

Symptom	Most likely cause	Check first
Never mines, but does chase	No pickaxe in the main hand (tool.require-pickaxe: true)	"main-hand pickaxe" in inspect
Does not even chase, as if the plugin were absent	Master switch off, or this world / mob filtered out	World and mob filter summary in status
Places one or two blocks, then stops	Placement count for this chase used up (max-per-chase default 32), or the backpack is empty	Placements used and backpack in inspect
Mines a bit, pauses, mines a bit	cooldown-seconds (default 8 s) after each block is broken	Cooldowns in inspect
Stares at a block and never mines	Target sealed off and out of sight, so the path-blocked trigger never fires	Turn on debug and read why candidates are skipped
Walks back and forth along water	Liquids are always avoided	See "Not placing" below
Ignores obvious drops on the ground	Pickup limits: gravity blocks, non-block items, occupied main hand	pickup.* settings and the backpack in inspect

Not mining

Symptom: the mob reaches the target, there is a block above its head, under its feet or in front of it, and it still does not mine.

Causes, most frequent first:

1. No pickaxe in the main hand. tool.require-pickaxe defaults to true, and without a pickaxe the mob takes no part in mining at all;
2. The mob failed the spawn-equipment gate. The gate is rolled once when the mob enters the world; a mob that failed it never receives blocks or a pickaxe on any path (see the first item of section 8);
3. The block is judged "cannot be mined": a computed duration above break-time.hard-cap-seconds (default 180) is skipped, and the console prints [MobInteract] OBSIDIAN 的挖掘耗时超过 hard-cap-seconds=… once per material;
4. The block is out of scope: the safety blacklist (bedrock, barriers, command blocks, structure blocks, portals, moving pistons, monster spawners, budding amethyst), outside world height or the world border, or a tile entity (chests, signs, furnaces) while safety.disallow-tile-entities: true (the default);
5. The block is not adjacent: with require-adjacent: true (the default) only blocks within ±1 horizontally and −1..+2 vertically are mined;
6. No trigger matches: when the target is completely sealed off and out of sight, the "path blocked" trigger never fires, because it relies on the vanilla target.

What to do: use inspect to read the main hand and the most recent behaviour, then check tool.require-pickaxe, tool.give.chance, break-time.hard-cap-seconds and materials.disabled / materials.allowed. If your scenario is "the target is walled in but the mob can see the wall", enable trigger.configured-blocks.enabled and add that block to .blocks so the mob digs whenever it sees the configured block.

Not placing (no bridging, no pillaring)

Symptom: a gap or a pillar separates the mob from the target, and the mob circles in place.

Causes:

1. No backpack: backpack.chance defaults to 0.65, and a mob that failed the roll never has blocks; placement.enabled: false also disables placement and pickup together;
2. The placement count for this chase is used up (placement.max-per-chase default 32), or the mob is waiting for a landing spot;
3. The height difference is only 1 block, or the drop ahead is ≤ 3 blocks — in those cases the plugin deliberately does not place anything and leaves it to vanilla walking / jumping;
4. The block ahead or the block under the feet ahead is a liquid: get out of the water first, no bridge or stairs across water; a target that can only be reached across water relies on vanilla swimming or detouring;
5. The landing position is occupied by a companion, or the target is in another region: the plugin re-plans up to 4 times, then skips this placement;
6. placement.pillar-up / stair-up / bridge was switched off, so that action is unavailable.

What to do: check in inspect whether the backpack is empty and whether the placement count hit the cap; check the placement summary in status. A long bridge or a tall pillar that stops halfway is almost always max-per-chase being too small — older versions defaulted to 10 and had exactly this problem; 32 or higher (range 0..512) is the fix.

Not picking things up

Symptom: there is cobblestone and a pickaxe on the ground, and the mob walks past.

Causes:

1. pickup.enabled: false, or placement.enabled: false (the placement master switch also controls pickup);
2. The drop is not "worth picking up": only placeable blocks and pickaxes are taken; gravity blocks such as sand and gravel, hard-blacklisted blocks (bedrock, monster spawners) and non-block items never are;
3. A pickaxe cannot be taken while the main hand is occupied — it is dropped back on the ground instead of disappearing;
4. pickup.reach (default 1.8) must be smaller than pickup.radius (default 8.0); otherwise it is lowered to radius / 2 with a console warning and the effective range shrinks;
5. A mob that is mining or placing (busy) is never interrupted to pick something up;
6. The mob failed the world / mob filter, or failed the spawn-equipment gate (with pickup.only-equipped enabled only mobs that passed the gate pick anything up).

What to do: check the relationship between pickup.radius and pickup.reach first, then drop valuables along a route the mob actually walks. If you want mobs that both carry blocks and can mine, raise chance in equip.yml.

Not chasing (no target)

Symptom: the mob ignores players entirely and does not care about villagers either.

Cause: both placement and mining require a chase target, and the target comes from vanilla targeting. Players in creative / spectator mode, in another world, or behind a wall and far away may simply not be a target.

What to do: targeting.yml has enabled: true by default and switches the target to the nearest survival / adventure player within 16 blocks, checked every 10 ticks; require-line-of-sight: false (the default) means it walks toward players even through walls. Keep keep-villager-target: true if you want the original villager target preserved when no player is around.

3. Obsidian will not break / mining stops halfway

Will not break

Cause: the duration is computed, not hard-coded. The effective multiplier is the per-block override in materials.multiplier when present, otherwise break-time.multiplier (default 4.0); a computed duration above break-time.hard-cap-seconds (default 180) counts as "cannot be mined" and is skipped. Obsidian has its own 6.0 override, so it is slower than 4.0 would suggest:

Block	Effective multiplier	Wooden pickaxe	Iron pickaxe	Diamond pickaxe	Default outcome
Obsidian	6.0	450 s	150 s	112.5 s	Wooden / stone pickaxe exceed the cap; iron and above can mine it
Ancient debris	8.0	360 s	120 s	90 s	Wooden pickaxe exceeds the cap
Reinforced deepslate	20.0	3000 s	1000 s	750 s	Never mineable by default

What to do: to mine obsidian, hand out iron or better (or raise tool.speed, or lower the materials.multiplier override); to make the mob give up faster, lower hard-cap-seconds. Remember that lowering it turns a whole group of hard blocks into "cannot be mined", and each material is reported once, so silence does not mean it never happened.

Stops halfway

Symptom: the crack progress is halfway, the block is still there, and the mob leaves; sometimes it comes back and starts over.

Causes:

1. The progress watchdog: 3 seconds (60 ticks) without any progress counts as a stall and abandons the action (inspect shows 挖掘停滞，已放弃), after which retry-seconds (default 1.5 s) applies;
2. After a block is broken, cooldown-seconds (default 8 s) must pass before the next block is considered, so clearing a tunnel takes several cooldown cycles;
3. Resuming works, but only within a window: same block and an interruption of at most 100 ticks (5 s) continue the previous progress, anything longer restarts from zero;
4. Vanilla AI grabbing control back, or a config reload in the middle, re-activates the action.

What to do: for long, hard blocks, first confirm the watchdog is not the one cutting it off (the stall message appears with debug on). Lowering cooldown-seconds speeds up consecutive mining but adds noticeable server load.

4. Bridges that never vanish / vanish too slowly

Never vanish

Symptom: the mob left long ago and the temporary blocks are still there, possibly forever.

Causes:

1. placement.block-lifetime-seconds is set to 0 — that means permanent, kept forever with only source tagging;
2. A player replaced the block with a different type: the block type is compared again before deletion, and a mismatch only drops the record, so "it is still there";
3. A living creature is within 1.2 blocks above the block (a mob crossing the bridge, a passing player): the expiry renews for a full cycle, so it keeps renewing while someone stands there;
4. The chunk is not loaded: the entry is retried after 5 seconds and is not lost, but it is not deleted right away either;
5. The registry is full (the 50,000-entry cap in section 8); evicted records are no longer protected and no longer expire.

What to do: check whether block-lifetime-seconds is 0, then whether something stands on that spot permanently. While diagnosing, turn on debug — the renewal decision is printed when a block expires.

Vanish too slowly

Cause: sweeping is a global sweeper that scans the expiry table every 20 ticks, merging expired blocks into one region task per chunk; region pauses or failed region submissions requeue the work, and unloaded chunks retry after 5 seconds. Blocks therefore disappear slightly later than the configured value — that is normal, not a broken setting.

What to do: lower block-lifetime-seconds (default 15, maximum 86400) if you want shorter lifetimes, but accept the risk of a block vanishing before the mob has crossed it. For long bridges over big gaps, keep the default and rely on the "renew while someone stands on it" rule.

Blocks left behind after a hard kill

Symptom: after kill -9 and a restart, the world contains a pile of unexplained cobblestone and dirt.

Cause: the temporary-block registry is in memory. A normal shutdown / restart removes every mob block; if the process is killed hard, the shutdown path is never reached and the blocks stay in the world, where only manual cleanup helps.

What to do:

1. Clean up manually (a WorldEdit selection replaced with air is fastest);
2. pending-blocks.txt in the plugin folder is the fallback for a shutdown / restart: the list is written to disk before the blocks are removed, and the next start cleans up again — this also covers a hard kill during shutdown, but not a kill -9 at runtime;
3. To avoid leftovers, do not kill the process while it runs; schedule cleanups as planned restarts at off-peak times.

5. Protection areas are ignored

Symptom: with a protection plugin such as WorldGuard or Residence installed, mobs still mine and place inside protected areas.

Cause: the plugin has no built-in integration with any protection plugin and allows everything by default. Protection has to be wired in from the outside: either register a "is this position protected?" check with this plugin, or listen to the cancellable event it emits before a mob changes a block. When several checks are registered, a single denial counts as protected.

What to do:

1. Ask whether your protection plugin offers an integration for this plugin; if not, use a script or a bridge plugin to register a check or listen to the block-change event;
2. Only BlockLocker works out of the box: once installed, the chests, doors, trapdoors and barrels it protects are neither mined nor blown up, and /mobinteract status shows "BlockLocker protection: yes/no". It is a soft dependency — nothing else changes without it;
3. A failing BlockLocker API call is treated as "not protected" (fail-open) and warns only once per instance. If you see that warning, look at BlockLocker itself rather than assuming a bug here.

6. Which mobs are taken over

Why villagers are not taken over

Cause: the default humanoid set is zombies (including drowned, husks, zombie villagers, zombified piglins), skeletons, illagers, piglins and witches. Villagers and wandering traders are not in that default set — they are targets, not actors.

What to do: to take them over, set mob-whitelist: [VILLAGER, WANDERING_TRADER]; mob-whitelist: ["*"] (or ALL / ANY) means every mob, and mob-blacklist always wins.

Slimes and ghasts do not mine; boats, armor stands, items and players cannot be taken over

Cause: mobs without a main-hand equipment slot (slimes, ghasts, ...) cannot hold a pickaxe, so they never mine under require-pickaxe: true; entities other than mobs (boats, armor stands, dropped items, players) are outside the scope of takeover entirely.

What to do: treat them as targets or decoration. The only way to make them mine is to turn require-pickaxe off, which gives up the "only mobs with a pickaxe mine" balance — usually not worth it.

Spawn equipment is rolled only once

Cause: the gate in equip.yml is rolled once when the mob enters the world and the result is recorded on that mob's profile; it is never re-rolled. A mob that failed the gate never receives blocks on any path (including the backpack roll at its first placement), and the same holds for pickaxes.

What to do: to equip a specific mob right now, respawn it or hand it the pickaxe / blocks directly (items placed in the main or off hand follow vanilla rules). To raise the overall share, change chance in equip.yml (default 0.10); inside the gate the pickaxe roll uses tool.give.chance (default 0.8) and the backpack roll uses backpack.chance (default 0.65).

7. Backpacks and drops

Backpacks are not persisted

Symptom: after a chunk unloads and reloads the backpack is empty, or the same mob shows up without its equipment.

Cause: the block backpack is virtual and lives in memory only; a mob that unloads and reloads rolls again, and blocks collected through pickup are lost with the entity.

What to do: this is a design trade-off, not a bug. For a long-lived "gatekeeper" mob, give it real items the vanilla way instead of relying on the virtual backpack; a long chase across chunks naturally drains the backpack.

Drops disappear / cannot be picked up

Causes:

1. A pickaxe cannot be taken while the main hand is occupied — it is dropped back on the ground (never swallowed), so look for it where the mob stood;
2. Gravity blocks (sand, gravel) and non-block items are never picked up;
3. With pickup.reach auto-lowered, the mob may never get close enough to reach the item;
4. Plugin-granted pickaxes never drop by default (tool.give.drop-chance: 0.0), but pickaxes a mob picked up still drop by vanilla rules, so players can recover them by killing the mob.

What to do: confirm the drop type is allowed; hand valuable gear to mobs the vanilla way rather than expecting them to keep carrying it.

8. Other known limitations

Mining and placement are mutually exclusive

As soon as a mob starts mining it yields the placement behaviour and keeps staring at the block being mined, so "mine and pave at the same time" never happens; the cost is that no new path laying starts while mining. If you want bridges first, reduce the situations that trigger mining (for example, stop sealing the target in).

One block at a time

After a block is broken, if something still blocks the way, the next decision waits for cooldown-seconds (default 8 s), so clearing a tunnel takes several cooldown cycles. Looking slow is expected.

The registry caps at 50,000 entries

The temporary-block registry holds at most 50,000 entries; beyond that the oldest records are evicted in insertion order, and evicted blocks are no longer protected and no longer expire automatically. Permanent blocks from block-lifetime-seconds: 0 make this more likely as they accumulate. Once it happens only manual cleanup helps, so consider giving permanent blocks a finite lifetime.

The /inspect "most recent behaviour" text cannot be changed

That line is a status string generated inside the behaviour (for example 放置次数已用完（max-per-chase=32）), shown directly by the plugin and outside the keys of message.yml. message.yml covers the regular player-facing texts (the output skeleton of status / inspect / reload), not this line.

Cracks are not visible

Crack progress uses a "nearby players" query; under very strict regionalised entity query policies it may find none, so no cracks are shown. This only affects the display, never whether the mining actually succeeds.

One fallback value differs from the yml

In rare cases (a key deleted from the file) a built-in fallback is used, and the TNT fuse-ticks fallback is 80 while the yml says 60. In the normal bundled files the yml wins, so do not delete keys and you will never see it.

The two kinds of "world settings" are not the same thing

Location	What it governs
equip.yml's chance and worlds.<world name>	Spawn-equipment chance: how likely a mob in that world is to spawn with a pickaxe / blocks (world names are case-insensitive)
worlds.whitelist / worlds.blacklist in mining.yml / placement.yml	Whether the behaviour applies: empty whitelist = all worlds, non-empty = only those worlds, blacklist wins

"Nothing happens in this one world" is usually the latter having a blacklist entry, not a problem with equip.yml.

9. Self-check scenarios

To find out whether a config change actually took effect, walk through these in-game scenarios (all of them were run one by one on a shared 26.3 server):

Scenario	Setup	Expected result
Ravine	6-block-wide ravine with a villager on the far side	Bridges the ravine and kills it
Pillar	Villager on top of a 6-block stone pillar	Pillars up and kills it
Distant platform	4-block-high platform 10 blocks away	Stairs + bridge
Drops	3 cobblestone + 1 stone pickaxe on the ground	Pickaxe into the main hand, blocks into the backpack, drops cleared
Villager and blocks	Villager + cobblestone on the ground	Villager not taken over, cobblestone left on the ground
Crowd	3 zombies chasing the same target	Detours / steps aside, never deadlocks
Blocked ceiling	Once without a pickaxe, once with one	Without: switch column and pillar; with: mine through the ceiling, then pillar in the same column
In water	Standing in a pool, target above the pool	No placement in water, gets out first
Floating target	Gravity-free villager in the air	Extends the bridge / pillars up to melee range
Drowned in water	Drowned in a pool + villager on a platform across the water	Drowned taken over, gets out and pillars up
Descending	Mob on top of a 5-block pillar, target on the ground below	Places one block below
Mine below	Target standing on a 2-block stone pillar	Mines under the target, the target falls
Lifetime	block-lifetime-seconds set to 5	Registered with a 5-second expiry, the block becomes air at the 7th second
Walled in with obsidian	Villager walled in with obsidian + diamond pickaxe, trigger.path-blocked enabled	Partial: the log shows mining of obsidian starting, but the scenario was never finished (the server was stopped externally)

Pay attention to the last row: the full obsidian mining path was never run to completion. When "obsidian stops halfway" happens, suspect the watchdog and hard-cap-seconds described above before assuming a misconfiguration.

Related pages

• Installation, upgrade and uninstall
• Mining
• Placement and path laying
• Backpack and pickup
• Spawn equipment and messages
• Commands and permissions
• Changelog