Troubleshooting Guide

This guide covers common issues and their solutions. If you don’t find your issue here, check the FAQ or open an issue.

Table of Contents

  1. Players Not Transferring to Limbo
  2. Revivals Not Working
  3. Players Lose Lives During Grace Period
  4. Admin Commands Not Working on Limbo Server
  5. Version Mismatch Warnings
  6. Database Connection Errors
  7. Players Reconnecting Go Straight to Limbo
  8. Extra Life Items Not Working
  9. Hardcore Hearts Not Showing
  10. Revival Ritual Structure Not Triggering
  11. Revive Skull Recipe Not Working
  12. Players Can’t Visit Limbo
  13. Plugin Not Loading

Players Not Transferring to Limbo

Symptoms

Solutions

- Check Server Role Configuration

On Main server:

is-limbo-server: false

On Limbo server:

is-limbo-server: true

- Verify Server Names Match Proxy

In your config.yml (both servers):

main-server-name: "main"
limbo-server-name: "limbo"

In your velocity.toml:

[servers]
  main = "localhost:25566"
  limbo = "localhost:25567"

The names must exactly match (case-sensitive).

- Check Database Connection

Both servers must connect to the same database:

  1. Check console logs for “Database connection established”
  2. Verify both servers have identical database credentials
  3. Test database connectivity from each server

- Verify Player Information Forwarding

For Velocity:

player-info-forwarding-mode = "modern"

For BungeeCord:


# config.yml

ip_forward: true

# spigot.yml on both servers

bungeecord: true

- Check Death Mode Configuration

In Main server config:

main:
  death-mode: "hybrid"  # or "limbo" for immediate transfer

If using spectator mode, players won’t transfer to Limbo automatically.

- Look for Plugin Messaging Errors

Check console logs for:

Revivals Not Working

Symptoms

Solutions

- Ensure HRM is Enabled

hrm:
  enabled: true
  structure-revive: true  # For ritual structures

- Verify Ritual Structure is Correct

Structure Requirements:

- Enable Structure Detection

In Main server config:

main:
  detect-hrm-revive: true

- Check Database Connectivity

Try manual revival to test database:


/psadmin revive <player>

If this works but structures don’t, the issue is with structure detection.

- Verify Both Servers Access Same Database

  1. Check that both servers show “Database connection established”
  2. Confirm identical database credentials on both servers
  3. Test database access from both server hosts

- Check Limbo Server is Running

The Limbo server must be running to process revivals:

Players Lose Lives During Grace Period

Symptoms

Solutions

- Check Grace Period Configuration

lives:
  grace-period: "24h"  # NOT "0" which disables it

Formats:

- Verify Grace Period Status


/pstatus <player>

Should show grace period remaining time.

- Set Grace Period Manually

For players who joined before enabling grace period:


/psadmin grace <player> 24

- Remember: Online Time Only

Grace period only counts while player is online:

Admin Commands Not Working on Limbo Server

Symptoms

Solution

This is normal security behavior! By default, OP users are blocked from using admin commands on the Limbo server to prevent abuse.

- Use Whitelist (Easiest - No permissions plugin required)

Edit config.yml:

limbo-trusted-admins:
  - "069a79f4-44e9-4726-a5be-fca90e38aaf5"  # UUID (recommended)

  - "PlayerName"                              # or username

Then reload from console (or from an already whitelisted/bypass-enabled admin):


/psadmin reload

Or simply restart the server to apply the changes.

- Grant Bypass Permission (Requires LuckPerms)

Use a permissions plugin like LuckPerms:


/lp user <player> permission set ssoggysouls.bypass-limbo-op-security true

This allows the OP to use admin commands on Limbo.

- Alternative: Remove OP and Use Explicit Permissions


/deop <player>
/lp user <player> permission set ssoggysouls.admin true
/lp user <player> permission set ssoggysouls.revive true

- Disable Security Check (Not Recommended)

In config.yml:

limbo-op-security-check: false

Warning: This removes the security protection and allows any OP on Limbo to revive/modify player data.

- Use Console

Console commands always work on both servers:


/psadmin revive <player>
/revive <player>

Version Mismatch Warnings

Symptoms

Solutions

- Update Both Servers to Same Version

  1. Download the latest SSoggySouls JAR
  2. Stop both servers

  3. Replace the JAR on both servers

  4. Start both servers

- Verify Versions Match

Check console logs on both servers:


[SSoggySouls] Version 3.2.6 enabled

Both must show the same version number.

- Clear Old Database Records (If Needed)

If switching from old version, you may need to:

DELETE FROM hardcore_players WHERE plugin_version IS NOT NULL;

Warning: This will reset all player data!

Database Connection Errors

(Note: This largely applies to type: "mysql". If you are using type: "sqlite", make sure your server has write permissions to the plugins/SSoggySouls/ folder to generate the database.)

Symptoms

Solutions

- Verify MySQL/MariaDB is Running


# Linux

sudo systemctl status mysql

# or

sudo systemctl status mariadb

# Windows

Check Services for MySQL

- Test Database Credentials

Use MySQL client to test:

mysql -h localhost -P 3306 -u ssoggysouls_user -p

Enter password when prompted. If this fails, your credentials are wrong.

- Check Firewall Rules

Ensure backend servers can reach database:


# Test connection

telnet database_host 3306

# or

nc -zv database_host 3306

- For Pterodactyl: Use Panel Host

Don’t use “localhost” - use the host provided by your panel:

database:
  host: "mysql.example.com"  # From panel, not "localhost"

  port: 3306

- Ensure Database Exists

CREATE DATABASE IF NOT EXISTS ssoggysouls;

- Check User Permissions

-- Restrict to the host your backend uses (e.g. 127.0.0.1 or your server IP)

GRANT SELECT, INSERT, UPDATE, DELETE ON ssoggysouls.* TO 'ssoggysouls_user'@'127.0.0.1';

FLUSH PRIVILEGES;

- Verify Connection Pool Size

For high-traffic servers, increase pool size:

database:
  pool-size: 10  # Default is 5

Players Reconnecting Go Straight to Limbo

Symptoms

Solution

This is intended behavior for hybrid mode!

In hybrid mode:

If you want different behavior:

Use spectator mode instead:

main:
  death-mode: "spectator"  # Dead players stay in spectator indefinitely

Extra Life Items Not Working

Symptoms

Solutions

- Confirm Extra Life is Enabled

extra-life:
  enabled: true

- Check Recipe Configuration

Verify all materials are valid Minecraft material names:

extra-life:
  recipe:
    row1: "DED"
    row2: "INI"
    row3: "GEG"
    ingredients:
      G: "GOLD_BLOCK"      # Must be valid material

      E: "EMERALD_BLOCK"
      N: "NETHER_STAR"
      D: "DIAMOND_BLOCK"
      I: "NETHERITE_INGOT"

- Verify Player is Not at Max Lives

Extra Life cannot exceed max lives:

lives:
  max-lives: 5  # Player can't gain lives beyond this

Check with:


/pstatus

- Ensure Player is Alive

Can’t use Extra Life while dead.

- Test Recipe

Try crafting with exact materials in the exact pattern defined.

Hardcore Hearts Not Showing

Symptoms

Solutions

- Enable in Configuration

hardcore-hearts: true

- Understand It’s Cosmetic Only

Hardcore hearts:

- Restart Server

After enabling, restart the server:


/psadmin reload

- Note: Client-Side Feature

This feature may require:

Revival Ritual Structure Not Triggering

Symptoms

Solutions

- Verify Structure is Exactly Correct

Common mistakes:

- Check Player Head is Correct

- Ensure Detection is Enabled

main:
  detect-hrm-revive: true

- Verify HRM is Enabled

hrm:
  enabled: true
  structure-revive: true

- Check Plugin is Listening for Block Places

Restart server if needed:


/psadmin reload

Revive Skull Recipe Not Working

Symptoms

Solutions

- Enable Recipe

hrm:
  revive-skull-recipe: true

- Use Correct Recipe (Shapeless)

Place anywhere in crafting grid:

Note: Order doesn’t matter (shapeless recipe).

- Restart Server

After enabling:


/psadmin reload

Players Can’t Visit Limbo

Symptoms

Solutions

- Check Permission

permissions:
  ssoggysouls.visit: true  # Should default to true

Grant permission:


/lp user <player> permission set ssoggysouls.visit true

- Verify Limbo Server is Online

Limbo server must be running for visits.

- Check Server Name Configuration

limbo-server-name: "limbo"  # Must match proxy config

- Ensure Player is Alive

Dead players can’t use /limbo - they’re already there!

Plugin Not Loading

Symptoms

Solutions

- Check Java Version

Requires Java 21 or higher:

java -version

- Verify Minecraft Version

Plugin supports 1.21.X only. Check server version:


/version

- Check Console for Errors

Look for:

- Verify Plugin File is Not Corrupted

  1. Re-download the JAR
  2. Check file size matches
  3. Replace old JAR with new one

- Check Plugins Folder

Ensure JAR is in plugins/ folder, not a subfolder.

Getting Additional Help

If your issue isn’t covered here:

  1. Enable Debug Mode

    ```yaml debug: true

```text

Restart both servers and reproduce the issue.

  1. Collect Information

    • SSoggySouls version

    • Minecraft version

    • Proxy type (Velocity/BungeeCord)

    • Relevant config sections

    • Console errors/logs

    • Steps to reproduce

  2. Search Existing Issues Check GitHub Issues for similar problems.

  3. Open a New Issue Create an issue with all collected information.

← Back to Home FAQ →