# 🛠️ Troubleshooting

Use this page before asking for support.

Most issues are caused by one of the following:

* Wrong installation location
* Missing Java 21
* Missing license key
* Redis misconfiguration
* Database misconfiguration
* PlaceholderAPI expansion installed in the wrong place
* PacketEvents not installed for packet-based features
* Incorrect permissions
* Command conflicts with another plugin
* Module disabled or not reloaded

***

### Basic Checklist

Before debugging a specific issue, check the basics first.

* NexusProxy is installed on the Velocity proxy.
* The proxy is running Java 21.
* The NexusProxy jar is inside the Velocity `plugins` folder.
* The plugin generated `plugins/NexusProxy/nexusproxy.yml`.
* The required modules are enabled.
* The proxy was restarted after installation.
* `/nexusproxy storage` shows the expected Redis and database status.
* The player has the correct permissions.
* Command names were not changed in module YAML files.
* No other plugin is overriding the same command.

***

### Plugin Does Not Start

If NexusProxy does not start, check the console logs first.

Common causes:

* Java version is not Java 21.
* NexusProxy was installed on a backend server instead of Velocity.
* The jar file is invalid or corrupted.
* License key is missing or invalid, if licensing is enabled.
* Configuration file contains invalid YAML.
* Required runtime libraries could not be loaded.
* File permissions prevent NexusProxy from creating folders or libraries.

***

### Fix: Plugin Does Not Start

Check that NexusProxy is installed here:

```
velocity/
└── plugins/
    └── NexusProxy-x.x.x.jar
```

Not here:

```
paper-server/
└── plugins/
    └── NexusProxy-x.x.x.jar
```

Check your Java version:

```
java -version
```

NexusProxy requires:

```
Java 21
```

If your build requires a license key, configure it in:

```
plugins/NexusProxy/nexusproxy.yml
```

Example:

```yaml
license:
  key: "YOUR_LICENSE_KEY"
```

{% hint style="warning" %}
NexusProxy is a Velocity plugin.

Do not install the main NexusProxy jar on Paper, Spigot, or Purpur servers.
{% endhint %}

***

### Configuration Does Not Generate

If `plugins/NexusProxy/` is not created after startup, check:

* NexusProxy is inside the Velocity plugins folder.
* The proxy fully restarted.
* Java 21 is installed.
* The jar file is not corrupted.
* Console logs do not show startup errors.
* File permissions allow the proxy to write inside the `plugins` folder.

Expected folder:

```
plugins/
└── NexusProxy/
    ├── nexusproxy.yml
    ├── modules/
    └── libraries/
```

***

### Module Does Not Load

If a module does not load, check its module file.

Module files are located inside:

```
plugins/NexusProxy/modules/<module>/<module>.yml
```

Make sure the module is enabled:

```yaml
module:
  enabled: true
```

Then restart the proxy or run:

```
/nexusproxy reload
```

You can check loaded modules with:

```
/nexusproxy modules
```

***

### Command Does Not Work

If a command does not work, check:

* The related module is enabled.
* The player has the required permission.
* The command was not renamed in the module YAML file.
* Another plugin is not using the same command.
* NexusProxy was restarted or reloaded after config changes.
* The command is being executed on the correct proxy/server context.

Example:

```
plugins/NexusProxy/modules/messaging/messaging.yml
```

If another plugin uses `/msg`, rename the command or aliases in the Messaging module configuration.

***

### Player Has No Permission

If a player cannot use a command, check:

* The exact permission required by the module.
* The permission is assigned in LuckPerms.
* The permission is assigned in the correct context.
* The player does not have a negative permission.
* The module permission was not customized in the YAML file.

Useful LuckPerms command:

```
/lp verbose on
```

Then ask the player to run the command again and check which permission is being checked.

***

### Redis / Global Online Not Working

Redis issues usually affect:

* Global online count
* Proxy online count
* Server online count
* Friends online status
* PlaceholderAPI expansion values
* Staff synchronization
* Synced announcements
* Synced donation broadcasts

Check that Redis is enabled in:

```
plugins/NexusProxy/nexusproxy.yml
```

Example:

```yaml
storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

***

### Fix: Redis / Global Online Not Working

Check that:

* Redis is enabled on every proxy.
* Every proxy uses the same Redis host.
* Every proxy uses the same Redis port.
* Every proxy uses the same Redis password.
* Every proxy uses the same Redis database.
* Every proxy uses the same `channel_prefix`.
* Every proxy has a unique `cluster.proxy_id`.

Correct example:

```yaml
# Proxy 1
cluster:
  proxy_id: "Proxy-1"
```

```yaml
# Proxy 2
cluster:
  proxy_id: "Proxy-2"
```

Incorrect example:

```yaml
# Proxy 1
cluster:
  proxy_id: "Proxy"
```

```yaml
# Proxy 2
cluster:
  proxy_id: "Proxy"
```

{% hint style="danger" %}
Never use the same `cluster.proxy_id` on multiple proxies.

Duplicated proxy IDs can break online counts, player presence, friends status, and synchronization.
{% endhint %}

Check Redis status:

```
/nexusproxy storage
```

***

### Database Not Working

Database issues can affect:

* Friends
* Known player profiles
* Ignored players
* Private message data
* HelpOp history
* PlaceholderAPI friends placeholders

Database settings are configured in:

```
plugins/NexusProxy/nexusproxy.yml
```

Supported database types:

```yaml
none
mysql
mongodb
mongo
```

***

### Fix: MySQL Not Connecting

Check that:

* MySQL server is running.
* Host is correct.
* Port is correct.
* Database name exists.
* Username is correct.
* Password is correct.
* The MySQL user has access to the selected database.
* The proxy can reach the MySQL server.
* `use_ssl` matches your database host requirements.
* `allow_public_key_retrieval` is configured correctly if needed.

Example:

```yaml
storage:
  database:
    type: "mysql"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "nexusproxy"
      username: "root"
      password: "password"
      use_ssl: false
      allow_public_key_retrieval: true
```

Check status:

```
/nexusproxy storage
```

***

### Fix: MongoDB Not Connecting

Check that:

* MongoDB server is running.
* MongoDB URI is correct.
* Authentication details are correct.
* Database name is correct.
* The proxy can reach MongoDB.
* The URI does not contain invalid characters or extra spaces.

Example:

```yaml
storage:
  database:
    type: "mongodb"
    mongodb:
      uri: "mongodb://localhost:27017"
      database: "nexusproxy"
```

***

### Friends Placeholders Return 0

Friends placeholders may return `0` if the Friends module, database, Redis, or PlaceholderAPI expansion is not configured correctly.

Check that:

* Friends module is enabled.
* Database storage is enabled.
* Friend data exists in the database.
* Redis is enabled if online friends are needed.
* PlaceholderAPI expansion uses the same database settings.
* PlaceholderAPI expansion uses the same Redis settings.
* The player actually has friends.

Proxy-side placeholders:

```
%friends_total%
%friends_online%
%friends_offline%
%friends_pending%
%friends_limit%
```

PlaceholderAPI expansion placeholders:

```
%nexusproxy_friends_total%
%nexusproxy_friends_online%
%nexusproxy_friends_offline%
%nexusproxy_friends_pending%
%nexusproxy_friends_limit%
```

{% hint style="info" %}
Redis handles online friend presence.

The database stores persistent friend relationships.
{% endhint %}

***

### PlaceholderAPI Placeholders Do Not Work On Lobby

The NexusProxy PlaceholderAPI expansion must be installed on backend servers.

Correct location:

```
backend-server/
└── plugins/
    └── PlaceholderAPI/
        └── expansions/
            └── expansion-nexusproxy.jar
```

Incorrect location:

```
velocity/
└── plugins/
    └── expansion-nexusproxy.jar
```

{% hint style="danger" %}
Do not install the PlaceholderAPI expansion jar on Velocity.

Install it inside the backend server's PlaceholderAPI expansions folder.
{% endhint %}

***

### Fix: PlaceholderAPI Placeholders Do Not Work

Check that:

* PlaceholderAPI is installed on the backend server.
* `expansion-nexusproxy.jar` is inside `plugins/PlaceholderAPI/expansions/`.
* The backend server was restarted or `/papi reload` was executed.
* The expansion config exists.
* Redis settings match NexusProxy.
* Database settings match NexusProxy if using friends placeholders.
* The required NexusProxy module is enabled.

Expansion config location:

```
plugins/PlaceholderAPI/expansions/NexusProxy/config.yml
```

Reload PlaceholderAPI:

```
/papi reload
```

Test a placeholder:

```
/papi parse me %nexusproxy_global_online%
```

***

### Global Online Placeholder Returns 0

Check that:

* Redis is enabled in NexusProxy.
* Redis is enabled in the PlaceholderAPI expansion.
* Both use the same Redis host.
* Both use the same Redis port.
* Both use the same Redis password.
* Both use the same Redis database.
* Both use the same `channel_prefix`.
* Every Velocity proxy has a unique `cluster.proxy_id`.

Example PlaceholderAPI expansion Redis config:

```yaml
redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: ""
  database: 0
  channel_prefix: "nexusproxy"
```

***

### Server Online Placeholder Returns 0

For placeholders like:

```
%nexusproxy_server_lobby_online%
```

Check that:

* The backend server name is correct.
* The server name matches Velocity exactly.
* Redis is enabled if using multi-proxy data.
* Players are actually connected to that backend server.
* The placeholder is typed correctly.

{% hint style="warning" %}
Server names are case-sensitive depending on your setup.

Use the exact backend server name configured in Velocity.
{% endhint %}

***

### Proxy Online Placeholder Returns 0

For placeholders like:

```
%nexusproxy_proxy_Proxy-1_online%
```

Check that:

* The proxy ID is correct.
* The proxy ID matches `cluster.proxy_id`.
* Redis is enabled.
* The target proxy is online.
* The PlaceholderAPI expansion uses the same Redis channel prefix.

{% hint style="warning" %}
Proxy placeholders use `cluster.proxy_id`, not `cluster.proxy_name`.
{% endhint %}

***

### HealthIndicator Does Not Work

HealthIndicator requires PacketEvents.

Check that:

* PacketEvents is installed on the Velocity proxy.
* The PacketEvents jar is the correct Velocity version.
* PacketEvents loaded successfully.
* HealthIndicator module is enabled.
* NexusProxy was restarted after installing PacketEvents.
* The player does not have `nexusproxy.healthindicator.bypass`.

Expected plugin folder:

```
velocity/
└── plugins/
    ├── NexusProxy-x.x.x.jar
    └── packetevents-velocity-x.x.x.jar
```

{% hint style="danger" %}
HealthIndicator will not work without PacketEvents.
{% endhint %}

***

### Toast Features Do Not Work

Toast features may be used by:

* Announcer
* Donations

Toast features require PacketEvents.

Check that:

* PacketEvents is installed on the Velocity proxy.
* PacketEvents loaded successfully.
* The related module is enabled.
* Toast settings are enabled.
* Toast configuration is valid.
* The proxy was restarted after installing PacketEvents.

***

### HelpOp Discord Bot Does Not Connect

HelpOp bot mode uses JDA runtime libraries downloaded by NexusProxy.

Check that:

* Bot mode is enabled.
* Discord bot token is correct.
* Discord channel ID is correct.
* The bot is invited to the Discord server.
* The bot has the required permissions.
* The proxy can connect to Discord.
* NexusProxy can download and load JDA libraries.
* Required libraries exist in `plugins/NexusProxy/libraries/`.

Example config concept:

```yaml
discord:
  bot:
    enabled: true
    token: "YOUR_BOT_TOKEN"
    log_channel_id: "123456789012345678"
```

{% hint style="danger" %}
Never share your Discord bot token publicly.

If it leaks, regenerate it immediately.
{% endhint %}

***

### Discord Webhook Does Not Send Messages

Check that:

* Webhook URL is correct.
* Webhook still exists in Discord.
* Webhook integration is enabled in the related module.
* The Discord channel still exists.
* The proxy can connect to Discord.
* The module event is actually being triggered.

Modules that can use webhooks include:

* Staff
* Report
* Donations
* HelpOp

{% hint style="warning" %}
Keep webhook URLs private.
{% endhint %}

***

### Commands Missing From Tab Complete

If commands are missing from tab completion, check the TabCompleteFilter module.

Configuration file:

```
plugins/NexusProxy/modules/tabcompletefilter/tabcompletefilter.yml
```

Check that:

* TabCompleteFilter module is enabled only if you want filtering.
* The command is allowed for the player's group.
* The player has the correct group permission.
* The player does not need bypass permission.
* The command is not in a deny or hidden list.
* NexusProxy was reloaded after editing the config.

Bypass permission:

```
nexusproxy.tabcompletefilter.bypass
```

{% hint style="info" %}
Command hiding and command permissions are different things.

A command can be hidden from tab completion but still executable unless denied.
{% endhint %}

***

### Runtime Libraries Do Not Download

NexusProxy may download optional runtime libraries into:

```
plugins/NexusProxy/libraries/
```

These may include libraries for:

* MySQL
* MongoDB
* Redis
* Discord bot mode / JDA

If libraries do not download or load, check:

* The proxy has internet access.
* The proxy can write to `plugins/NexusProxy/libraries/`.
* File permissions are correct.
* The required feature is enabled.
* The proxy was restarted after enabling the feature.
* Console logs do not show download or class loading errors.

{% hint style="info" %}
You normally do not need to manually install runtime libraries.

NexusProxy handles them when optional features are enabled.
{% endhint %}

***

### Announcements Do Not Send

Check that:

* Announcer module is enabled.
* The announcement exists in `announcer.yml`.
* The command sender has the correct permission.
* The announcement type is configured correctly.
* NexusProxy was restarted or reloaded.
* Redis is configured if manual announcements should sync across proxies.
* PacketEvents is installed if the announcement uses toast.

***

### Donation Broadcasts Do Not Send

Check that:

* Donations module is enabled.
* The command sender has the correct permission.
* Broadcast format is configured correctly.
* Discord webhook is valid if using Discord.
* PacketEvents is installed if using toast effects.
* Redis is enabled if broadcasts should sync across proxies.
* NexusProxy was restarted or reloaded.

***

### Staff Chat Does Not Sync Across Proxies

Check that:

* Redis is enabled.
* Every proxy uses the same Redis settings.
* Every proxy uses the same `channel_prefix`.
* Every proxy has a unique `cluster.proxy_id`.
* Staff module is enabled on every proxy.
* Redis sync is enabled in the Staff module, if configurable.

***

### Friends Show As Offline

Check that:

* Redis is enabled.
* Friends module is enabled.
* Every proxy uses the same Redis settings.
* Every proxy has a unique `cluster.proxy_id`.
* The target friend is actually online.
* Database storage is enabled for persistent friend data.

***

### Queue Does Not Work

Check that:

* Queue module is enabled.
* Player has `nexusproxy.command.queue`.
* Queue target exists in `queue.yml`.
* Backend server names match Velocity.
* Target permission is assigned if required.
* Holding server exists and is online, if used.
* Another plugin is not using `/queue`.

***

### MOTD Does Not Change

Check that:

* MOTD module is enabled.
* `motd.yml` is configured correctly.
* NexusProxy was restarted or reloaded.
* Another plugin is not overriding the proxy ping response.
* The player refreshed the multiplayer server list.

If maintenance mode is active, also check the Maintenance module MOTD settings.

***

### Maintenance Mode Does Not Work

Check that:

* Maintenance module is enabled.
* Maintenance is actually turned on.
* The player does not have `nexusproxy.maintenance.bypass`.
* The player is not whitelisted.
* The correct scope is enabled if using scoped maintenance.
* The backend server is included in the active scope.

Check status:

```
/maintenance status
```

***

### Another Plugin Is Using The Same Command

If another plugin uses the same command, change the NexusProxy command or aliases in the related module file.

Examples:

```
plugins/NexusProxy/modules/messaging/messaging.yml
plugins/NexusProxy/modules/friends/friends.yml
plugins/NexusProxy/modules/lobby/lobby.yml
plugins/NexusProxy/modules/staff/staff.yml
```

After editing, restart or reload NexusProxy.

***

### What To Send When Asking For Support

When asking for support, provide useful information.

Include:

* NexusProxy version
* Velocity version
* Java version
* Error from console
* Related module configuration
* Whether Redis is enabled
* Whether database storage is enabled
* Output of `/nexusproxy storage`
* What command or feature is not working
* Steps to reproduce the issue

{% hint style="warning" %}
Remove private information before sending configs.

Do not share license keys, database passwords, Redis passwords, Discord webhook URLs, or bot tokens.
{% endhint %}

***

### Safe Information To Share

You can usually share:

* Module name
* Command used
* Error message without secrets
* Java version
* Velocity version
* NexusProxy version
* Whether Redis is enabled
* Whether database is MySQL, MongoDB, or none

***

### Private Information To Remove

Always remove:

* License key
* MySQL password
* MongoDB URI password
* Redis password
* Discord webhook URL
* Discord bot token
* Server IPs if you want to keep them private

***

### Final Debug Checklist

Before opening a support ticket, verify:

* Java 21 is installed.
* NexusProxy is installed on Velocity.
* The required module is enabled.
* The proxy was restarted after installation.
* Permissions are assigned correctly.
* Redis is connected if the feature needs Redis.
* Database is connected if the feature needs storage.
* PacketEvents is installed if the feature needs packet support.
* PlaceholderAPI expansion is installed on the backend server, not Velocity.
* No other plugin is overriding the same command.
* `/nexusproxy storage` shows the expected status.

***

### Summary

Most NexusProxy issues come from installation location, missing dependencies, wrong Redis or database settings, missing permissions, command conflicts, or confusing proxy-side placeholders with the backend PlaceholderAPI expansion.

Check the related module page, verify dependencies, and use `/nexusproxy storage` before asking for support.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nexusproxy.nemesismc.net/help/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.