> For the complete documentation index, see [llms.txt](https://docs-nightbeam.gitbook.io/infinity-rifts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-nightbeam.gitbook.io/infinity-rifts/docs/troubleshooting.md).

# Troubleshooting

Start with `logs/latest.log`, confirm Java 21, then compare the running JAR version and `plugins/InfinityRifts/` files with this documentation. Enable `general.debug` and the relevant gateway's `random-spawn.debug.enabled` only while diagnosing noisy spawn behavior.

## Plugin does not load

**Symptoms:** red plugin name, `UnknownDependencyException`, or no InfinityRifts banner. **Cause:** missing/disabled PlaceholderAPI, Java below 21, incompatible server API, wrong/corrupt JAR, or an initialization exception. **Fix:** install PlaceholderAPI first, run the server on Java 21, use a Bukkit-family 1.20+ server, and use the shaded/obfuscated production artifact. Search for `Failed to initialize InfinityRifts!` and the following stack trace.

## Configuration warnings or load failure

**Symptoms:** `Configuration validation warnings for ...`, `Failed to load config.yml`, `Failed to load gateway file`, or a gateway missing from `/rift list`. **Cause:** malformed YAML, a wrong enum/material/mob name, invalid numeric range, missing Mythic mob, or duplicate/empty ID. **Fix:** validate YAML spacing, compare with [configuration](/infinity-rifts/docs/configuration.md), restore from backup, then restart. Validator text that says “using” a value does not necessarily mutate it; correct the value yourself.

The shipped Fire preset's nested `random-spawn.random-gates` path is ignored; move it to top-level `random-gates`.

## Command not found or permission denied

**Symptoms:** `/rift` unknown, Bukkit permission message, or configured no-permission message. **Cause:** plugin disabled, root `infinityrifts.use` denied, or undeclared admin nodes not assigned. **Fix:** verify plugin enable state and assign the exact nodes in [permissions](/infinity-rifts/docs/permissions.md). Only `/rift give` supports console.

## Gateway key does nothing

**Symptoms:** right-click has no effect or reports a condition failure. **Cause:** item lacks `infinityrifts:gateway_id`, is used off-hand, gateway ID was renamed/deleted, player is already active, or spawn conditions fail. **Fix:** generate a fresh key with `/rift give`, use main hand, inspect the target gateway's condition block, and grant only the required permission/bypass if appropriate. Failed conditions do not consume the key.

## Mobs do not spawn / wave fails

**Symptoms:** spawn warnings, wave stays in spawning, or gateway fails with zero mobs. **Cause:** invalid entity/Mythic name, unavailable MythicMobs, obstructed/unsafe locations, protection radius, unloaded/wrong world, or invalid mob health/amount. **Fix:** read the structured warning containing gateway/wave/type/location/reason; test a vanilla `ZOMBIE`; correct `type` (`minecraft:ZOMBIE` or `mythic:Name`), increase spawn radius/attempt limits, and clear the area. Validator message `no valid mob entries remain` identifies schema issues.

## Random rifts do not appear

**Symptoms:** no scheduled portals. **Cause:** `enabled: false`, long check interval, chance roll, active/world cap, world override disabled, biome/height/distance/clearance restriction, or old schedules after reload. **Fix:** enable debug, temporarily use a short valid interval and 100% chance on a test server, confirm world/biome spelling, and restart after edits. `/rift reload` does not restart the scheduled checks.

## GUI does not open or errors

**Symptoms:** permission message, invalid inventory-size exception, blank/stone items. **Cause:** missing `infinityrifts.admin`, `gui.admin-panel.rows` outside a viable six-row layout, or invalid materials. **Fix:** grant the node, restore `rows: 6`, and use Bukkit material names. The accent material is currently unused.

## Placeholders stay at `0`/`false`/`None`

**Symptoms:** PlaceholderAPI parses the identifier but shows fallback values. **Cause:** the expansion queries legacy `RiftManager` while normal gateways use `GatewayManager`. **Fix:** confirm `/papi parse me %infinityrifts_in_rift%`; if the expansion is registered and the normal gateway path is active, this is a known implementation limitation with no configuration fix.

## MythicMobs integration fails

**Symptoms:** `MythicMob not found`, `Error spawning MythicMob`, linkage errors, or mobs vanish incorrectly. **Cause:** wrong internal name, MythicMobs absent/disabled, API version mismatch, or invalid Mythic configuration. **Fix:** verify exact case/name in MythicMobs, test its own spawn command, use the API-compatible version, and use `/mm debug 3` for Mythic skill errors. Main `mythicmobs.enabled` does not control the integration.

## Rewards or economy fail

**Symptoms:** invalid material warnings, no money, or `Unknown command` for reward commands. **Cause:** invalid Bukkit material, `rewards.money` is unused, or the external command owner is absent. **Fix:** use valid materials; express economy via a console command backed by an installed economy plugin; test the exact command as console. `%player%` and `%uuid%` are the only reward-command replacements.

## Data does not restore

**Symptoms:** session gone after restart, `Failed to parse active rifts`, or no restoration on join. **Cause:** malformed/missing YAML, removed gateway ID, ownerless rift, or shutdown did not run. **Fix:** stop cleanly, restore a version-matched backup, ensure the gateway exists, and inspect the storage log. The plugin clears loaded records after moving them into memory; another crash before player join can therefore lose pending restoration.

## Stuck bars/entities or reload issues

Use a full restart. If tagged mobs remain, check shutdown/cleanup warnings and remove them administratively after backup. Avoid `/reload`; stale region tasks, GUI listeners, boss bars, and service instances can survive in unsafe states.