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

# Troubleshooting

Common issues and how to fix them.

## Plugin fails to load

**Symptom:** AuthSystem does not appear in `/plugins` or the console shows errors on startup.

**Possible causes and fixes:**

| Cause                       | Fix                                                               |
| --------------------------- | ----------------------------------------------------------------- |
| Wrong Java version          | AuthSystem requires Java 21. Check with `java -version`           |
| Wrong Paper version         | AuthSystem requires Paper 1.21.8                                  |
| Missing database config     | Ensure `plugins/AuthSystem/config.yml` has valid database details |
| Database server unreachable | Check MySQL/MariaDB is running and accessible from your server    |

## Cannot connect to database

**Symptom:** Console shows `SQLException` or `CommunicationsException`.

**Fixes:**

1. Verify `database.host`, `database.port`, `database.username`, `database.password`, and `database.name` in `config.yml`
2. Make sure MySQL/MariaDB is running
3. Check that your server's IP is allowed to connect to the database
4. If `database.ssl` is `true`, ensure the database supports SSL
5. Test the connection manually from your server machine

## Players are kicked immediately on join

**Symptom:** Players are kicked seconds after joining.

**Fixes:**

1. Check `auth.timeout-seconds` — if set too low, players don't have time to log in
2. Make sure players know to run `/register` or `/login` immediately on join
3. Check if the player has exceeded the brute-force limit

## Brute-force ban not expiring

**Symptom:** A player remains banned after the ban time has passed.

**Fixes:**

1. AuthSystem tracks bans in-memory; restarting the server clears temporary bans
2. Check `auth.ban-time` — the value is in seconds (default: 600)
3. If using an external ban plugin, that plugin may be enforcing the ban

## Commands not working for unauthenticated players

**Symptom:** Players get "You must be logged in" when trying to run commands.

**Fix:** This is expected behavior. Unauthenticated players can only run authentication commands (`/register`, `/login`, `/changepassword`, `/premium`, `/auth ...`). They must register or log in first.

## Password not recognized

**Symptom:** `/login` says the password is incorrect even though it's correct.

**Fixes:**

1. Make sure there are no extra spaces in the password
2. Passwords are case-sensitive
3. If the player changed their password recently, they must use the new one
4. An admin can reset the password with `/auth changepassword <player> <newPassword>`

## /auth reload does nothing

**Symptom:** Running `/auth reload` produces no visible change.

**Fixes:**

1. Make sure you have the `authsystem.command.reload` permission (or are opped)
2. Check the console for errors after running the command
3. Some config changes require a full server restart, not just a reload

## Language not changing

**Symptom:** Messages remain in English after changing `generic.lang`.

**Fixes:**

1. Make sure the language code matches a file in `plugins/AuthSystem/lang/` (`EN_us` or `IT_it`)
2. Restart the server or run `/auth reload`
3. Check the console for language-loading errors

## Still having problems?

Check the [FAQ](/authenticationsystem/faq.md) or contact support. When reporting an issue, include:

* Your Paper version
* Your Java version
* The relevant console error
* Your `config.yml` (with passwords removed)

***

> :bulb: **Tip**: Enable `generic.update-checker: true` to be notified when a new version of AuthSystem is available.