Wiki Release: 2026.09.8 · UltimateRaids: 0.12.0 · Documentation branch: 1

UltimateRaids troubleshooting#

Troubleshoot UltimateRaids in layers. Do not change ten YAML sections at once.

Start with:

/uraid validate <raid>
/uraid status raid <raid>
/uraid debug implementations

Then identify which layer is failing: definition → admission/lobby → environment → loadout → stage/objective → rewards → cleanup.

Fast diagnostic checklist#

1. Does the raid load and appear in /uraid list?
2. Does /uraid validate <raid> report an error?
3. Can one player join in a simplified test configuration?
4. Does the environment prepare and teleport correctly?
5. Does stage 1 start?
6. Does the objective/wave progress?
7. Does the raid finish/fail correctly?
8. Are player state and runtime worlds restored/cleaned?

Raid file does not load#

Check YAML syntax, top-level id, duplicate IDs, unsupported enum values and console errors during definition reload.

Use the bundled examples as syntax references. If a web/editor tool generated the file, still run validation after placing it on the server.

Raid has no stages / will not validate#

A raid must have at least one stage. A stage must also make sense for its completion mode:

• OBJECTIVE needs a real objective;
• WAVES needs waves;
• BOTH needs both;
• target IDs must resolve to what the stage actually spawns.

Player cannot join#

Check in this order:

1. enabled: true;
2. availability day/time window;
3. player/group/global cooldown;
4. requirements;
5. min/max player/group rules;
6. group provider registration;
7. leader-only queue rules;
8. lifecycle state (LOADING_INSTANCE, finishing/resetting/busy);
9. concurrent minigame slot capacity.

A “join denied” problem is usually not fixed inside stages/bosses.

MINIGAME cannot use SOLO#

MINIGAME entry requires PUBLIC, GROUP or COMPETITIVE. If you need one-player content, use NORMAL + SOLO instead.

/uraid start <raid> says MINIGAME is managed#

That is expected. A MINIGAME is controlled by the persistent matchmaking/lobby flow. Join through its queue/sign/NPC. Use force start only for deliberate admin testing of the existing queue.

Ready lobby never starts#

Check:

• ready-join.enabled;
• require-all;
• actual Ready count;
• min players;
• minimum wait;
• vote state/retry;
• countdown;
• start-when-full.

Use /raid status and /raid vote status to see live lobby state.

Vote succeeds but nothing starts#

Verify the lobby is still eligible, enough players remain, no instance slot is busy and instance preparation did not fail after the vote.

GROUP raid says provider unavailable#

group-provider must match a registered implementation. modules.yml priority does not prove the provider loaded.

Run:

/uraid debug implementations

If you expect UltimateClans or another group integration, verify the corresponding extension/provider is installed and loaded.

KIT raid says kit is missing#

Check:

• file exists under kits/;
• kit id matches the raid loadout.kit;
• /uraid kit reload succeeds;
• the kit can be viewed/given manually.

KIT raid did not restore inventory#

Do not delete storage or repeatedly rejoin until you inspect the state.

Check whether the player has pending loadout/recovery state and whether the flow ended through normal plugin management. Test the same kit with:

• lobby leave;
• completion;
• failure;
• admin stop;
• disconnect/reconnect.

If only one exit path fails, the problem is lifecycle-specific rather than the kit definition itself.

Player teleports to the wrong location#

Check whether the location is RELATIVE or absolute and what origin is being used at runtime.

For INSTANCE, remember that the runtime world is not the same world object/name as the template. RELATIVE locations are usually safer for portable instance definitions.

INSTANCE player spawns in the void#

Check in this order:

1. Did the template/schematic load successfully?
2. Is the runtime origin correct?
3. Is player-spawn relative to the intended origin?
4. For SCHEMATIC, is paste Y high enough and geometry actually below the spawn?
5. For VOID, did you create/paste a floor before teleport?
6. Is safe-ground/spawn adjustment being assumed where it is not configured?

Use a simple survival stage and no boss while fixing environment/spawn issues.

INSTANCE WORLD fails validation#

The template must exist and be a valid Minecraft world with level.dat. Do not point template at a disposable runtime clone.

INSTANCE SCHEMATIC provider unavailable#

Verify WorldEdit or FastAsyncWorldEdit and run /uraid debug implementations. Confirm the .schem exists under instances/schematics/ with the exact configured filename.

Schematic pasted but raid origin is wrong#

Paste coordinates and raid origin are separate concepts. Verify both. The bundled schematic example intentionally configures a paste position and a separate RELATIVE origin offset.

Instance loading times out#

Check template size, schematic paste, chunk preload settings and timeout-seconds. Do not blindly increase timeout until you know whether the loader is actually progressing.

Runtime instance world remains after finish/crash#

Check delete-on-finish, recovery configuration and startup recovery logs. Do not manually delete a world that the server still has loaded.

Players can leave the arena#

Bounds and border solve different problems.

• Bounds can enforce a cuboid and teleport players back.
• Border can be VISUAL, PHYSICAL or BOTH.

If you selected only a visual border, seeing the border does not imply physical enforcement.

Border does not display#

Check enabled, border mode and registered border provider. AUTO uses the provider selection system; confirm with /uraid debug implementations.

Multiple mobs spawn on the same block#

Add spawn spread:

spread:
  radius: 4
  safe-ground: true
  vertical-search: 8
  attempts: 12

A group with amount > 1 and zero spread is expected to start from the same configured point.

Mobs spawn in bad/unsafe locations#

Use safe-ground, vertical search and a sensible spread radius. Also verify the spawn point is relative to the intended origin and inside the actual built room.

KILL_ENTITIES never completes#

Compare:

objective.target

with:

waves.<wave>.groups.<group>.entity-id

They must match. The entity Bukkit type (ZOMBIE) is not the tracking target.

KILL_BOSS never completes#

Compare objective target with boss.id. Verify the spawned group actually contains a boss definition and the boss entity is tracked.

Stage says BOTH but never completes#

Both the objective and wave side must be complete. If all mobs are dead but objective progress is wrong, fix the objective target. If objective is complete but tracked entities remain, inspect wave/entity cleanup.

SURVIVE/CAPTURE seems too slow or too fast#

Use a small amount while testing. For CAPTURE, check how many players are inside, minimum-players, reset-on-empty and decay.

DEFEND fails immediately#

Make sure the defend target actually spawns/is tracked before the objective evaluates it. Check target ID and fail-on-target-death behavior.

ESCORT never progresses#

UltimateRaids tracks destination arrival but does not magically make an entity walk there. Confirm the native/provider AI is moving the target and that the destination/objective location is reachable.

DESTROY does not count block breaks#

Check:

• objective material/target;
• optional objective location restriction;
• active participant status;
• environment block-break rules;
• whether another protection plugin cancels the break first.

COLLECT does not count items#

Check material/custom item/provider and whether the player is an active participant. For custom items, verify provider registration.

Boss phase does not trigger#

Check phase health thresholds and ordering. Make thresholds descend logically from higher health to lower health. Confirm the skill IDs referenced by the phase are loaded.

Boss enrage does not trigger#

Check enabled, health percentage, after-seconds, and whether the boss survives long enough. If an enrage skill is referenced, verify the skill file loads.

Boss minion does not spawn#

Check minion provider/type, trigger condition, phase ID if applicable, interval and max-alive. Verify the entity provider is active.

Reward not granted#

Identify the reward type first.

• ITEM: item/provider and overflow policy.
• MONEY: economy provider.
• COMMAND: console command syntax/replacements.
• LOOT_TABLE: table ID and entries.
• EXPERIENCE/MESSAGE: player must still be resolvable at grant time.

Enable/log reward failures where configured and inspect the first failure rather than later symptoms.

Loot table gives unexpected results#

Check:

• selection: CHANCE vs WEIGHTED;
• number of rolls;
• guaranteed entries;
• unique;
• allow-duplicates;
• PERSONAL vs SHARED distribution.

Weighted values are relative weights, not percentages unless your weights happen to sum to 100.

Money requirement/reward fails#

Confirm an economy provider is registered and that the configured provider ID matches it. Do not assume Vault integration exists merely because Vault is installed; verify the UltimateRaids implementation/extension is active.

Custom item/entity does not resolve#

Use an explicit provider during debugging and run /uraid debug implementations. Then check the custom ID with the provider plugin itself.

Scheduler did not run#

Check:

• scheduler enabled;
• timezone;
• day;
• exact HH:mm time;
• minimum-online;
• target raid enabled/valid;
• FIXED vs RANDOM selection/pool;
• OPEN_LOBBY vs FORCE_START;
• restart recovery window;
• cancel-empty-after behavior.

Test immediately with:

/uraid scheduler run <scheduler>

If manual scheduler run fails, waiting for the clock will not fix it.

NPC cannot be created#

Join NPC creation is limited to compatible raid flows (MINIGAME or DISCOVERY) and requires EntityWizard. Verify raid mode and provider availability.

Dynamic sign cannot be registered#

Dynamic raid signs are for enabled MINIGAME raids. The sign header must be recognized and the raid ID must resolve.

Sign/NPC shows old raid state#

Check persisted registration still points to the current raid ID, especially after rename. Refresh/reload through the plugin and verify the target chunk/world is loaded when debugging signs.

Search/display placeholders look wrong#

Confirm you are using placeholders supported by the relevant display context. Entry/lobby displays and PlaceholderAPI expansion do not necessarily expose the exact same placeholder names.

YAML problems involving yes/no#

Some YAML tooling interprets unquoted yes/no as booleans under YAML 1.1. Avoid changing command/config map keys into ambiguous boolean-looking forms. Use the distributed files as the canonical structure.

A generated Builder file validates but gameplay is wrong#

The UltimateRaids Builder creates configuration structure; it cannot know whether your real-world spawn/bounds/map geometry or external providers are correct. Validate, capture/verify world locations, then do a full live test.

Still stuck — collect a useful support report#

Provide:

• UltimateRaids version;
• raid ID;
• exact symptom;
• /uraid validate <raid> output;
• /uraid debug implementations output if integrations are involved;
• relevant raid/kit/loot/scheduler file;
• first related console warning/error;
• entry/participation/loadout/environment/progression modes;
• whether the problem happens on join, start, stage progress, reward or cleanup.

This is far more useful than sending only “raid does not work”.