Alpha-systemHelpTroubleshooting

Troubleshooting

The problems server owners actually hit, matched to the console line or symptom you will see.

On this page

Startup
Database
Menus
Chat and display
Gameplay
Economy
Integrations

Check the server console first. Alpha-system logs a specific line for most of these problems, and /as diagnostics shows whether the database, Vault, PlaceholderAPI and webhooks are connected. Each card gives the symptom, the likely cause and the fix.

Startup

Console: Alpha-system is disabled — this server is waiting for approval.

Cause: A new server starts as pending, and the plugin stays off until AlphaStudio approves it.
Fix: Send the server id from the next console line to AlphaStudio, then restart once it is approved. See Server approval.

Console: Configuration validation failed with N error(s)

Cause: config.yml has broken YAML or an invalid value, such as an unknown enum, an out-of-range number or a bad respawn entry. Each problem follows as a [Config validator] line with its exact path. The plugin disables itself at startup.
Fix: Fix each listed path and restart. On /as reload the same check runs, but a failure only keeps your running config instead of disabling anything.

Console: Could not migrate config.yml

Cause: The update could not rewrite config.yml to the new layout, so the plugin disables itself rather than guess.
Fix: Check the message after the colon. Usually the file is unreadable or the folder is not writable. Restore a backup of config.yml if you have one.

Database

Console: Punishment system (ban/mute/warn/jail) failed to start - check your database config

Cause: The database connection failed. The line before it reads Failed to connect to the punishment database with the reason.
Fix: For MySQL, check host, port, database, username, password and use-ssl, and that the host allows your server's address. /as diagnostics confirms the fix.

Console: Database schema version N is newer than supported version M

Cause: You put an older jar back on a database that a newer version already upgraded. Older code does not know the new schema.
Fix: Run the newer jar again, or restore a database backup taken before the update.

Console: Database writes did not finish within 30 seconds

Cause: On shutdown the plugin waits up to 30 seconds for queued writes, and the database was too slow or unreachable.
Fix: Check the database host and disk. Changes made just before the stop may be missing.

Menus

Console: [Menu validator] … and Invalid menu files were replaced in memory with bundled defaults

Cause: A file under menus/ has an invalid item or key. While it is broken, players see the bundled default menu instead.
Fix: Fix the file named in the log and run /as reload. Your file on disk is never overwritten. Reopen the menu to see the change.

Chat and display

Console: PacketEvents is unavailable — exact single-line chat deletion is disabled

Cause: PacketEvents is not installed. The plugin still loads, and the [x] button falls back to replaying only Alpha-system's own messages.
Fix: Install PacketEvents for exact deletion on offline-mode servers. See Chat deletion.

Two names show above players when nameplates are on

Cause: PacketEvents is missing, so the vanilla name tag cannot be hidden. The console logs custom nameplates are visible but vanilla player names cannot be hidden.
Fix: Install PacketEvents. See Nameplates.

Console: Unresolved nameplate placeholder

Cause: A placeholder in nameplates.lines is not a built-in and no PlaceholderAPI expansion provides it.
Fix: Install the expansion or correct the name. unresolved-placeholders: hide removes it from the label, keep shows it for debugging.

Gameplay

Players are told they cannot use a command or teleport

Cause: They are combat-tagged. Commands in combat.blocked-commands, command teleports, ender pearls, chorus fruit and flight are refused for combat.tag-seconds.
Fix: Wait it out, or give staff alphasystem.combat.bypass. See Combat tag.

Console: No valid respawn destination for X; retaining Minecraft's original respawn location

Cause: None of the entries in respawn.priority gave a usable location. For CUSTOM, the location is missing or respawn.custom.enabled is false.
Fix: Run /setrespawn, or add SPAWN or WORLD_SPAWN to the list. A line Unknown respawn.priority entry means a name was misspelled.

/restart only stops the server

Cause: The console says Couldn't determine how this server was launched or Failed to relaunch the server process for /restart, so the plugin could not start a new process.
Fix: On a host that restarts the server for you, set restart.relaunch-process: false. Otherwise start the server with a normal java command line.

Economy

Other plugins cannot see Alpha-system's money

Cause: Vault is not installed. Alpha-system only registers as the Vault provider when Vault is present at startup.
Fix: Install Vault and restart. /as diagnostics shows whether the provider registered.

/moneyrollback refuses to reverse a transaction

Cause: The id does not exist, it was already reversed, or the receiver no longer has enough money to give back.
Fix: Check the id with /moneyhistory <player>. History older than transaction-history.retention-days (90 by default) is deleted.

Integrations

Console: Failed to send Discord webhook

Cause: The webhook URL is wrong, deleted or rate limited, or the host blocks outgoing HTTPS.
Fix: Test the URL from the same machine. Leave webhook-url empty to turn the feature off.

Console: A new version is available

Cause: The update checker compared your version with the latest release of the configured GitHub repository.
Fix: Nothing is broken. Update when you like, or set update-checker.enabled: false.