🩺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.

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.

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.

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.

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

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).