疑難排解Troubleshooting

所有依賴 Vault 的插件都失效了

[TSMPlugin] net/milkbowl/vault/economy/Economy does not exist
[AuctionHouse] NoClassDefFoundError: net/milkbowl/vault/economy/Economy

這些是連鎖反應，不是各自獨立的問題。往上找 Vault3 自己的載入錯誤，修好它們就會一起恢復。

jar 損毀

InvalidPluginException: java.util.zip.ZipException:
  ZipFile invalid LOC header (bad signature)

檔案在上傳時壞了，伺服器連 jar 的第一個項目都解不開。用 FTP 請選 Binary 模式，傳完比對 SHA-256。

重複插件

plugins/ 裡同時存在 Vault.jar 和 Vault3，或是換版本時舊 jar 沒刪。兩者都宣告插件名 Vault，其中一個會載入失敗。

一開選單就崩

java.lang.IncompatibleClassChangeError:
  Found class org.bukkit.inventory.InventoryView, but interface was expected

裝錯建置了。1.21 以上要用標準建置，1.20 以下要用 legacy 建置。指令能用但選單會崩是這個問題的典型特徵。詳見相容性。

MySQL 設定沒有生效

不會有任何錯誤訊息，只會靜默套用預設值。檢查兩個鍵名：

連線參數是 params，不是 properties
連線池參數必須巢狀在 pool: 底下

改了 MySQL 設定但沒反應

/vault reload 不會重新連線資料庫。連線設定變更需要重啟伺服器。

餘額在重啟後倒退

先看關服時的 console 有沒有 Saved N player balances before shutdown.。若看到失敗訊息，插件資料夾裡應該有 balances-emergency-*.yml。確認 storage.recover_emergency_dumps 為 true，下次啟動會自動補寫。

PlaceholderAPI 變數沒有替換

PlaceholderAPI 找不到識別碼時不會報錯，只會讓變數原樣顯示。確認：

PlaceholderAPI 已安裝，且啟動時有出現 expansions registered 那行
變數拼寫正確 —— 見變數

進服或交易時卡頓

3.0.0 已移除主執行緒上的資料庫查詢與全表寫入。若仍有卡頓，用 spark 之類的工具確認是不是其他插件在主執行緒上呼叫 Vault Economy 的 String 形式 API。

Every Vault-dependent plugin broke

[TSMPlugin] net/milkbowl/vault/economy/Economy does not exist
[AuctionHouse] NoClassDefFoundError: net/milkbowl/vault/economy/Economy

These are knock-on effects, not separate problems. Scroll up for Vault3's own load error; fixing it brings all of them back.

Corrupted jar

InvalidPluginException: java.util.zip.ZipException:
  ZipFile invalid LOC header (bad signature)

The file was damaged in transfer — the server cannot even read the first entry. Use binary mode for FTP and compare SHA-256 afterwards.

Duplicate plugin

Vault.jar and Vault3 are both in plugins/, or an old jar was left behind during an upgrade. Both declare the plugin name Vault, so one fails to load.

Menus crash on open

java.lang.IncompatibleClassChangeError:
  Found class org.bukkit.inventory.InventoryView, but interface was expected

Wrong build. Use the standard build on 1.21+, the legacy build on 1.20 and below. Commands working while menus crash is the signature of this problem. See Compatibility.

MySQL settings have no effect

There is no error — the defaults are applied silently. Check two key names:

The connection string key is params, not properties
Pool settings must be nested under pool:

Changed MySQL settings, nothing happened

/vault reload does not reconnect the database. Connection changes require a server restart.

Balances rolled back after a restart

Check the console at shutdown for Saved N player balances before shutdown. If you see a failure instead, look for balances-emergency-*.yml in the plugin folder. With storage.recover_emergency_dumps set to true, the next start applies it automatically.

Placeholders are not being replaced

PlaceholderAPI does not error on an unknown identifier; it just leaves the text as-is. Check:

PlaceholderAPI is installed and the expansions registered line appeared at startup
The placeholder is spelled correctly — see Placeholders

Lag on join or during transactions

3.0.0 removed main-thread database queries and whole-table writes. If lag persists, use a profiler such as spark to check whether another plugin is calling the legacy String form of the Vault Economy API on the main thread.