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

# Troubleshooting

## The plugin disables itself on startup

NetworkEconomy deliberately refuses to run in a state where balances could be wrong. There are two causes, both logged at `SEVERE`:

**`Failed to connect to the database. Disabling.`** The database is unreachable or the credentials are wrong. Check `storage.host` / `port`, that the database named in `storage.database` **already exists**, and that the user may connect from the server's IP. The cause is appended to the log line.

**`Invalid currency configuration`** The `currencies:` section is missing or empty. At least one currency must be declared — see [currencies.md](/products/networkeconomy/currencies.md).

## Balances differ between two servers

Work through these in order:

1. **Are both servers pointed at the same database?** Different `storage.database` values mean two independent economies.
2. **Do both have `redis.enabled: true` and the same `channel`?** A mismatched channel means broadcasts are published where nobody is listening.
3. **Do the two servers have different `server-id` values?** A node ignores broadcasts stamped with its own id — two servers sharing an id will ignore each other's updates entirely.
4. **Check the console for `Redis failed to start; running in DB-only mode.`** In that mode, updates propagate only every `cache.fallback-refresh-seconds`.

{% hint style="info" %}
A brief difference is normal and harmless: the caches only affect the number being *displayed*. Transactions are always evaluated against the database, so a stale display can never cause a wrong deposit, withdrawal or transfer.
{% endhint %}

## Redis failed to start

```
Redis failed to start; running in DB-only mode. Cause: ...
```

The plugin stays fully functional — the database remains authoritative — and falls back to refreshing online players' caches on a timer. Common causes:

* Wrong `host` / `port`, or Redis not running.
* A password set on Redis but left empty in the config (or the opposite).
* `redis.username` filled in for a Redis that does not use ACL users — leave it empty unless you actually have an ACL user.

Fix the connection and restart; there is no data to recover, since Redis only carries invalidation messages.

## Vault plugins do not see the economy

* Is Vault installed? Without it, the console logs `Vault not found; the Vault Economy bridge is disabled.`
* Is another economy plugin also registering a Vault provider? Remove it — with two providers, Vault plugins may read from one and write to the other.
* On success the console logs `Registered NetworkEconomy as the Vault economy provider.` Confirm with Vault's own `/vault-info`.

## A Vault plugin only sees one currency

That is expected. Vault has no concept of multiple currencies, so the bridge exposes only the **default** currency. Non-default currencies are reachable through NetworkEconomy's commands and API only.

## The server lags when a Vault plugin touches the economy

Vault's API is synchronous, so the bridge has to block briefly (bounded by a 5-second timeout) to return an accurate answer. Reads are served from the cache for online players, but a plugin that calls the economy in a tight loop or on every tick will feel it.

The fix is on the calling plugin's side: use the native async API. See [for-developers.md](/products/networkeconomy/for-developers.md).

## A player says they lost money

The transaction log is append-only and nothing is ever overwritten, so the truth is always recoverable:

* `/transactions <player>` shows every change, newest first, including which server it happened on and the reason string.
* Admin actions are stamped `admin:<staff name>`, `/pay` as `pay:<sender>`, and Vault-plugin activity as `vault`.

A reason of `vault` with no matching in-game action usually means a third-party plugin charged them.

## /baltop looks out of date

Pages are cached for `commands.baltop.cache-seconds` (default 60). Lower it if you want fresher rankings, but the cache exists to keep a frequently used command from repeatedly running a full sort over the balances table.

## Duplicate or missing history entries after a rejoin

Balances are loaded during the async pre-login event and cleared on quit. A player who reconnects rapidly may briefly have a stale cache entry — this affects only what the display shows, never the stored balance, and resolves at the next read or cache expiry.

## Enabling debug output

```yaml
debug: true
```

Logs SQL and Redis traffic verbosely. It is noisy, so turn it back off once you have what you need.

## Errors mentioning Netty or Lettuce

If you built the plugin yourself and see class-loading conflicts around Netty, the shading configuration was likely altered. All bundled libraries **must** stay relocated under `com.ohalee.networkeconomy.lib` — Paper ships its own Netty and Lettuce requires a newer one, so an unrelocated build clashes with the server at runtime. Likewise, `minimize` must stay off, since it would strip classes that are only reached reflectively (the JDBC driver, Netty handlers, Lettuce codecs).