Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• API/src/main/java/xyz/xreatlabs/nexauth/api/configuration/CorruptedConfigurationException.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconMessages.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/HoconPluginConfiguration.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticMySQLDatabaseConnector.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticPostgreSQLDatabaseConnector.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java
• API/src/main/java/xyz/xreatlabs/nexauth/api/Logger.java
• Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java

This document provides guidance for diagnosing and resolving common issues encountered while using NexAuth. It covers startup failures, runtime errors, and the use of built-in troubleshooting tools. The primary sources of problems are often misconfigurations, database connection issues, or environmental incompatibilities.

NexAuth is designed to fail fast and provide clear error messages. In many critical failure scenarios, such as an inability to connect to the database or a corrupted configuration file, the plugin will intentionally shut down the server or proxy to prevent data corruption or security vulnerabilities.

Common Startup Failures

Startup is a critical phase where NexAuth validates its configuration, environment, and database connectivity. Failures at this stage are common and usually result in the server shutting down.

Corrupted Configuration

A CorruptedConfigurationException is thrown if config.conf or messages.conf is malformed, contains invalid values, or is missing required keys. The plugin logs a detailed error and shuts down.

The error message typically includes the root cause of the parsing failure, which is extracted using the GeneralUtil.getFurthestCause method.

Example Error Log:

!! THIS IS MOST LIKELY NOT AN ERROR CAUSED BY NEXAUTH !!
!!The configuration is corrupted, please look below for further clues. If you are clueless, delete the config and a new one will be created for you. Cause: [ExceptionType]: [ExceptionMessage]

This message format helps distinguish between a plugin bug and a user-side configuration error.

The diagram below illustrates the configuration loading process and where it can fail.

This diagram shows the sequence of loading configuration files and the immediate shutdown upon failure.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:444-477, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurateConfiguration.java:48-52, API/src/main/java/xyz/xreatlabs/nexauth/api/configuration/CorruptedConfigurationException.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/util/GeneralUtil.java:38-46

Database Connection Issues

NexAuth will fail to start if it cannot connect to the configured database. This is often due to incorrect credentials, network issues, or an invalid database type specified in config.conf.

The connection process is as follows:

1. Read the database.type from the configuration.
2. Look up the corresponding DatabaseConnectorRegistration.
3. Instantiate the connector (e.g., AuthenticMySQLDatabaseConnector).
4. Attempt to connect using credentials from the database.properties section.
5. If the connection fails, log an error and shut down the proxy with exit code 1.
6. If a transient connection error occurs during runtime, the proxy will also shut down to prevent data loss.

This diagram shows the initial database connection flow and the critical failure path during runtime if the connection is lost.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:372-426, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticMySQLDatabaseConnector.java:60-72, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/database/connector/AuthenticPostgreSQLDatabaseConnector.java:58-70

Unsupported Server Environment

NexAuth for Paper requires an Adventure-compatible server distribution (like Paper or its forks). During the onLoad phase, it checks if the server environment is supported. If not, it logs a severe error and shuts down the server.

// From PaperBootstrap.java
private void unsupportedSetup() {
    getLogger().severe("***********************************************************");
    getLogger().severe("Detected an unsupported server distribution. Please use Paper or its forks. SPIGOT IS NOT SUPPORTED!");
    getLogger().severe("***********************************************************");
    stopServer();
}

This check ensures that the required APIs are available, preventing runtime errors.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java:32-38, 71-77

Runtime Errors and Player Kicks

These issues occur while the server is running and typically affect individual players.

Common Kick Reasons

Players can be kicked for various reasons, most of which are configurable. The kick messages are defined in messages.conf.

Kick Message Key	Default Message	Cause & Relevant Configuration
kick-ip-limit	You have reached the maximum amount of accounts per IP!	The player's IP address has exceeded the registration limit. Set by ip-limit.
kick-time-limit	You took too long to authorize!	The player did not log in or register within the allowed time. Set by seconds-to-authorize.
kick-name-mismatch	Oh no! It looks like an premium user...	A profile conflict occurred. See profile-conflict-resolution-strategy.
kick-invalid-case-username	Please, change your username to &c%username%	The player joined with a username that has a different capitalization than the one stored in the database.
kick-no-lobby / kick-no-limbo	There's no available lobby/limbo to connect you to...	No available and online server was found in the lobby or limbo lists.
kick-error-password-wrong	Wrong password!	The player exceeded max-login-attempts with an incorrect password.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/MessageKeys.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java

Update Checker Failures

The plugin checks for updates on startup. It uses a multi-layered approach for reliability. If you see warnings about update checks failing, it means all fallback methods were unsuccessful.

This diagram shows the update checker's fallback mechanism, starting with the GitHub API.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:696-840

Troubleshooting Tools

NexAuth includes several commands to help administrators diagnose issues.

/nexauth dump

This command is the most powerful tool for reporting bugs. It collects a wide range of system and plugin information into a single JSON file.

Information Collected:

• NexAuth Version & Dump Date
• Server Information (Name, Plugins, Servers, Limbo/Lobby config)
• Detailed Thread Dump (ID, Name, State, Stack Trace)

This diagram outlines the structure of the JSON file generated by the dump command.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java:68-150

Reload Commands

You can reload parts of the plugin without restarting the entire server.

Command	Permission	Description
/nexauth reload configuration	librepremium.reload.configuration	Reloads config.conf. Throws an error if the new config is corrupt.
/nexauth reload messages	librepremium.reload.messages	Reloads messages.conf and injects the new messages into the command system.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/command/commands/staff/NexAuthCommand.java:152-192

Debug Mode

Enabling debug mode provides more verbose logging, which can be useful for tracking down complex issues. This is controlled by a configuration key.

• Key: debug
• Type: Boolean
• Default: false
• Description: If true, prints additional debug messages to the console.

Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:386-391, API/src/main/java/xyz/xreatlabs/nexauth/api/Logger.java:60-67