Troubleshooting

Detailed solutions for common issues. If your problem isn’t here, check the FAQ or open an issue on Modrinth.

Plugin Not Loading

Symptoms

No [InviteMe] messages in server console on startup
/invite and /im commands don’t exist
/plugins doesn’t show InviteMe

Checklist

1. Check Java version

java -version

InviteMe requires Java 21 or higher. If you see Java 17 or lower, upgrade your Java installation.

2. Check server software InviteMe requires Paper (or a Paper fork). Pure Spigot and CraftBukkit are not supported.

Verify your server version in the console startup line:

[Server] Starting Paper version git-Paper-...

3. Check the JAR is in the right place

plugins/
├── InviteMe-x.x.x.jar   ← must be here
└── ... other plugins

4. Check console for errors Look for lines like:

[ERROR] Could not load 'plugins/InviteMe-x.x.x.jar'

The error message will tell you exactly what’s wrong.

5. Run debug If the plugin loads but something’s wrong:

/im debug

Players Can’t Join Despite Being Invited

Quick Checks

/invite list          ← confirm the player is actually in the list
/im debug             ← check access control mode and storage status
/im sync              ← resync whitelist with InviteMe database

Case 1: Player not in the list

/invite list

Check the action log for removals:

/im log list PlayerName

Case 2: Whitelist out of sync (native mode)

In native mode, InviteMe writes to whitelist.json. If it got out of sync:

/im sync

This adds any missing players back to whitelist.json.

Case 3: Plugin mode with whitelist still enabled

In plugin mode, server.properties must have:

white-list=false

If white-list=true, Minecraft will reject the player before InviteMe can allow them.

Restart the server after changing server.properties (reload alone is not enough).

Case 4: Invitation expired

Temporary invitations expire silently. Check:

/im log list PlayerName

To re-invite:

/invite add PlayerName
/invite add PlayerName 30

Commands Not Working

”Unknown command”

Verify InviteMe is loaded: /plugins → look for InviteMe [enabled]
Check the exact spelling: /invite and /im (not /invites or /iminvite)
If just installed, the server needs to be restarted (not just reloaded)

“You don’t have permission”

Run /im debug and check the permissions section. Then:

For /invite add not working:

# If you changed defaults, restore:
/lp group default permission set invite.use true

For /invite add Player 7 (days) not working:

/lp user PlayerName permission set invite.temp true
/lp group vip permission set invite.temp true

For /invite remove not working:

/lp user PlayerName permission set invite.admin true

Command works but nothing happens

Check storage status:

/im debug
# If "Error" or "Disconnected", see Database Issues below

Invitation Limit Issues

Player hits their limit too quickly

Check their current limit:

/im profile PlayerName

If using LuckPerms group limits:

/im debug

/lp user PlayerName info

Increase limit in config.yml:

default-invite-limit: 10    # increase this

Or grant a per-player override:

/lp user PlayerName permission set invite.number.10 true

Then reload:

/im reload

Player has invite.admin but still shows a limit

invite.admin bypasses all limits. If the profile still shows a limit, the permission may not be active:

/lp user PlayerName permission check invite.admin

Database Issues

”Connection failed” (MySQL/PostgreSQL)

Step 1: Verify config.yml credentials

storage:
  type: mysql
  remote:
    host: your-host.com     ← correct?
    port: 3306              ← correct port?
    database: inviteme      ← database exists?
    username: inviteme_user ← correct username?
    password: "password"    ← correct password?

Step 2: Test from the server machine

mysql -h your-host.com -u inviteme_user -p inviteme

psql -h your-host.com -U inviteme_user inviteme

If this fails, the issue is network connectivity or credentials — not InviteMe.

Step 3: Check firewall

MySQL: port 3306
PostgreSQL: port 5432
Both must be open from your Minecraft server’s IP

Step 4: Verify the database user has correct permissions

-- MySQL
SHOW GRANTS FOR 'inviteme_user'@'%';
-- Should include: GRANT ALL PRIVILEGES ON inviteme.*

-- PostgreSQL
\du inviteme_user

”Data seems to be missing after migration”

After migrating backends, run sync to verify:

/im sync
/im debug

The original data is preserved:

SQLite: plugins/InviteMe/invites.db.migrated
JSON: plugins/InviteMe/invites.json.migrated

If data is missing, you can migrate back from the .migrated file by renaming it and running the migration again.

SQLite “database locked” error

SQLite uses file locking. This happens when:

Two processes access the same file simultaneously
A previous crash left a lock file

Fix:

# Delete the lock file if it exists:
rm plugins/InviteMe/invites.db-shm
rm plugins/InviteMe/invites.db-wal

/invite list

If /invite list shows invitations but the GUI is empty, try:

/im reload
/invite menu

Right-click doesn’t open confirmation dialog

Make sure you’re right-clicking the player head, not an empty slot
Check you have the invite.use permission
Close and reopen the menu

Heads show as Steve (default skin)

Player heads use Minecraft’s skin system. They’ll show as Steve if:

The player never joined the server (offline-mode issue)
The skin API is temporarily unavailable

This is cosmetic only — functionality is not affected.

LuckPerms Integration Issues

Group limits not applying

/im debug

If it shows “Not installed”:

LuckPerms may not have loaded before InviteMe
Restart the server (don’t just reload)

If installed but limits wrong:

/lp user PlayerName info

# Group names must match EXACTLY (case-sensitive)

invite.admin always bypasses limits

This is intentional behavior. Players with invite.admin:

Bypass all invite limits
Can see all players in the GUI
Can remove any invitation

If you want to restrict a specific admin, remove invite.admin and grant individual permissions instead.

Configuration Issues

Changes to config.yml not taking effect

/im reload
/im debug   ← verify new values are shown

If values still don’t change, check for YAML syntax errors. Common mistakes:

password: P@ssw0rd!

password: "P@ssw0rd!"

storage:
type: mysql    ← must be indented

storage:
  type: mysql

Use an online YAML validator (search “YAML lint”) to check your file.

config.yml keeps getting reset

InviteMe only creates config.yml if it doesn’t exist. If it’s being overwritten:

Check for other plugins that might be managing config files
Verify file permissions: plugins/InviteMe/config.yml must be writable

Performance Issues

Server lag after installing InviteMe

InviteMe runs all storage operations asynchronously and should not cause server lag. If you notice lag:

Enable debug mode and check for slow queries:
```
debug-mode: true
```
Then /im reload and watch for slow operation warnings in console.
For MySQL/PostgreSQL, increase pool-size if you have many players:
```
storage:
  remote:
    pool-size: 20
```
Switch from JSON to SQLite or MySQL — JSON reads the entire file on every operation.

Getting More Help

If these steps don’t resolve your issue:

Run /im debug and copy the full output
Check recent server console logs for InviteMe errors
Open an issue at Modrinth Discussions with:
- Your server version (/version)
- InviteMe version (/im debug)
- The full error from console (if any)
- Steps to reproduce the issue