Skip to content

Troubleshooting

Start here whenever something does not work:

/dungeon validate <id>
/dungeon validate all
/dungeon reload

Also check the server console. Validation warnings in chat are shorter than the console output.

Dungeon Will Not Open

Check:

  • dungeons/<id>/config.yml exists.
  • The config uses the current format marker.
  • The template world exists and is loaded.
  • Spawn and exit are set.
  • Min/max players are valid.
  • The dungeon passes /dungeon validate <id>.

Dungeons using the 1.x config format must be recreated for 2.x.

Boss Dungeon Does Not Complete

Check:

  • The dungeon was created as boss.
  • boss.yml exists.
  • The boss location is valid.
  • boss.must-die-to-complete is true if boss death should complete the run.
  • The boss entity spawned inside the instance world.

Trigger Dungeon Does Not Complete

Check:

  • The dungeon was created as trigger.
  • trigger.yml exists.
  • The trigger was placed with /dungeon settrigger <material>.
  • The trigger block still exists in the template or instance.
  • The material is a supported button or pressure plate.

Tower Does Not Continue

Check:

  • dungeon-type: tower.
  • tower-stage-type is correct.
  • next-dungeon points to an existing dungeon.
  • The next dungeon passes validation.
  • Only the FIRST stage has entry costs.
  • Free version towers are only FIRST -> LAST.

Stage Gate Does Not Open

Check:

  • Stage files are in dungeons/<id>/stages/.
  • Stage orders are continuous: 1, 2, 3.
  • The gate was saved with /dungeon gate save.
  • Active missions are complete.
  • Later stages do not progress until earlier gates open.

Loot Chests Are Empty

Check:

  • The loot chest config has loot entries.
  • Chances are above 0.
  • The placed chest was created with /dungeon lootchest give <id>.
  • Custom item provider plugins are loaded.

Players Get Removed From Instance Worlds

In the Free Paper 1.21.x build 2.3.1, startup verifies that all participants reach the instance before starting the run. A failed entry cancels startup and refunds entry costs. Respawning is tracked separately from leaving the dungeon.

For that build, set debug: true in the main config.yml and run /dungeon reload to investigate teleport problems. Keep the complete console log from preparation through cleanup. [Teleport] lines include the requested destination, API result, event cancellation, player state, and actual world after the event. eventSeen=false means no teleport event was observed for that attempt. [Respawn] lines record respawn destinations and arrival checks. Registered listeners are diagnostic candidates; the list does not prove which plugin cancelled a teleport.

Active instance worlds reject players who are not part of the dungeon run. This prevents outside players from entering temporary worlds.

If this happens to real dungeon players, check:

  • They did not leave the party.
  • They did not disconnect during start.
  • The party is still active.
  • They did not use external teleport commands into another instance.

Custom Items Fail

Check:

  • The integration plugin is installed and loaded.
  • The item ID is correct.
  • Run /dungeon status.
  • Use the integration lookup command when available:
/dungeon mythicitem [itemId]
/dungeon itemsadder [itemId]
/dungeon oraxen [itemId]
/dungeon nexo [itemId]