# FAQ & Troubleshooting

**Version:** 2.6.6

## General

### How do players open the bank?

- At a **bank NPC**: a KyuubiSoft Core citizen with **BANK: Yes** (`bankingEnabled`), see [Getting Started](./getting-started#5-set-up-a-bank-npc).
- With `/ksbank open`, or `/ksbank page <page>` for a specific page.

`/ksbank` on its own only lists the subcommands.

### Does the bank work without KyuubiSoft Core?

Yes, as storage: the commands, the bank window, pages, history and the admin panel work. Without Core there are no bank NPCs (they are Core citizens), no economy (Account tab and paid pages; every page is free) and no automatic merging of new config fields.

### How many pages can a player have?

Players start with `defaultPages` (1). They can buy pages up to `maxPages` (5), or up to their [rank pages](./permissions#rank-pages) limit when `rankPages` is set. A page can only be bought when the price list has a price for it. Admins can grant pages up to `maxPages` with `/ksbank adminupgrade` or the admin panel.

### Why can players unlock pages for free?

Pages are free when their price is `0` and **whenever the server has no economy**: without an economy the price is shown as "Free" and the purchase goes through. Install KyuubiSoft Core, VaultUnlocked and an economy plugin, or stop purchases (next question). From 2.7.0 (not released yet) switching on the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) is enough.

### How do I stop players from buying pages?

Switch **Upgrades Enabled** off in the admin panel's General section (`upgrade.enabled: false`). Players then get "Bank pages cannot be bought on this server."; admins can still grant pages. To sell pages only to some players, set a node in `permissions.upgrade` or use [rank pages](./permissions#rank-pages).

### Can I change the number of slots per page?

Yes, also on a running server. Saved pages are fitted the next time a bank opens: raising the value adds empty slots, lowering it moves the items of cut-off slots to free slots. Items without a free slot wait in the player's file and come back when there is room; the player gets a chat message while items wait. See [Configuration](./configuration#slotsperpage).

### Can players trade items straight from the bank?

No. Items have to be taken into the inventory first. Only coins can be turned into money (Account tab).

---

## Saving

### When is the bank saved?

When the window closes (X, Escape), before it is redrawn (page purchase, view switch), every 60 seconds while it is open, when the player logs out and when the server stops. Admin changes save at once.

### Are items safe if the server crashes?

A crash loses at most what a player changed in an open bank window since the last 60-second save. Each save keeps the previous file as `<uuid>.json.bak`.

### Items from a removed mod are missing in the window

Stacks whose item no longer exists on the server (for example after removing a mod) cannot be shown, but they stay stored in the bank. The player gets "N item(s) from removed mods are kept in your bank but cannot be shown." and the log shows `Hiding N item(s) in bank for <name>`. Once the mod is installed again, they show up again.

Opening the bank still removes such items from the player's own **inventory** (log: `Removed N invalid item(s) from player inventory`), because the client cannot show them there. Keep a backup of the player data before you remove a mod whose items players carry.

### A player's bank is suddenly empty

If `players/<uuid>.json` could not be read (for example after a manual edit with a JSON error), the player got a new, empty bank. The old file was copied to `<uuid>.json.unreadable-<time>` first (the log says so). Stop the server, fix the copy and put it back as `<uuid>.json`.

### "Page N of your bank could not be read"

The saved data of that page is damaged. The page is locked in the window and its saved data is never overwritten, so nothing is lost. Look for the page number in the log and check the player's file.

---

## Economy and coins

### Which economy plugins work?

Every economy that registers with **VaultUnlocked**, together with KyuubiSoft Core. Core finds it; the bank uses it for the Account tab and page prices. The **General** section of the admin panel shows the provider it found ("Economy Provider").

### The Account tab is missing

The Account tab only appears when Core found an economy and the bank is your own. Check that Core, VaultUnlocked and an economy plugin are installed and that **Economy Provider** is not "Not available". Admins looking into another player's bank never see it. From 2.7.0 (not released yet) the tab also appears while the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) is on.

### The Account tab has no "Deposit coins" or "Withdraw as coins"

The selected currency has no coin items. Coins are looked up by the economy provider name:

- EcotaleCoins are added automatically under the provider `Ecotale`.
- For other coins add them in the admin panel's **Coins** section under a provider with exactly the name shown as "Economy Provider".

### "You are not allowed to do this" in the Account tab

The server limited that feature to a permission node (`permissions.transfer`, `withdraw` or `deposit` in `config.json`). Grant the node, or leave its `permission` empty to allow everyone. See [Permissions](./permissions#feature-permissions-in-configjson).

### The balance shows the wrong currency name

The word under the balance is the provider's entry in `upgrade.providerDisplayNames`, otherwise the currency name the economy reports. Set a display name for the provider in the admin panel's **Economy** section.

### How does withdrawing as coins work with odd amounts?

Only the part that fits into whole coins is paid out and taken from the balance. With a smallest coin of 10, withdrawing 15 pays one coin and keeps 5 in the account. Below the smallest coin nothing happens.

### Can players send money to offline players?

Not in 2.6.6: the receiver must be online. From 2.7.0 (not released yet) yes, with every economy: everyone who has played on the server can receive money, with an optional reason, and both people get a history entry. See [UI Pages](./ui-pages#the-account-tab-from-270).

### What is Kronen?

KyuubiSoft's own server currency ("Crowns" in English), coming with Bank 2.7.0 and Core 2.10.0 (both not released yet). The bank can carry it without Core; it is off by default and steps back when another economy is installed. See [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/).

### My Ecotale coin values reset after a restart

The `Ecotale` coin list is rebuilt from EcotaleCoins on every start and reload. Change coin values in EcotaleCoins, not in the bank.

---

## Restrictions

### How do wildcards work?

A `*` in `restrictedItems` stands for any run of characters: `Quest_*` blocks every item whose ID starts with `Quest_`, `*_Key` every ID ending in `_Key`. Upper and lower case do not matter. The list is checked for clicks, drag and drop and the game's own container moves.

### An item I just restricted is still in a bank

Restrictions only stop items from going in. Items that were stored before stay in the bank and can still be taken out.

### How do I switch to whitelist mode?

Set `"restrictionMode": "whitelist"` in `config.json` and run `/ksbank reload`. The admin panel only shows the mode. An empty list allows everything.

---

## World banking

### How do I give the PvP worlds their own bank?

Add a group in the admin panel's **Worlds** section (for example `pvp` with `arena, battleground`) and switch **World Banking Enabled** on. A world whose name contains one of the entries (case does not matter) uses that group's bank. See [Configuration](./configuration#worldbanking).

### What happens when a player changes worlds?

Nothing in the bank itself. The next time they open it, they get the bank of the world group they are in, or the normal bank. Each bank keeps its own items and pages.

### Pages bought with `/ksbank upgrade` are missing in my world group bank

`/ksbank upgrade` always upgrades the normal bank. Buy pages for a world group bank in its Pages tab while you are in that group's worlds.

---

## Admin

### How do I look into a player's bank?

`/ksbank open --player=<name>` (or `--player=<uuid>` for offline players), or **Players** > **Open Bank** in the admin panel. You can move items between the vault and your own inventory; the owner's money, pages and settings cannot be changed. See [UI Pages](./ui-pages#another-players-bank).

### "Player not found" for a player who exists

Names only find **online** players. For offline players use their UUID with the commands. The Players and History sections of the admin panel only find online players.

### What happens when I change a bank the player has open?

`/ksbank give`, `adminupgrade`, `reset` and the admin panel's **Reset Bank**, **+ Add Page** and **- Remove Page** first save and close the player's bank window, then apply the change. The change sticks.

### Does a reset delete the history?

No. `/ksbank reset` and **Reset Bank** empty the pages and reset the page count; the history in `bank.db` stays.

### The admin commands answer "No permission!" or cannot be run

You need `ks.bank.admin`, see [Permissions](./permissions). The old `bank.admin` is no longer used.

### Players only see part of their history

Players see their newest `historyMaxEntries` entries (100 by default). Set it to `0` for no limit. The database keeps every entry; `/ksbank log` and the admin panel's History section are not limited.

---

## Troubleshooting

### The bank does not open

- Check that the log shows `Bank System ready.`
- Look for `Failed to open bank for <uuid>` in the log.
- An admin trying to open a player's bank gets "Bank is already open!" while the player has it open.

### "Maximum bank size reached!" although the player should have more pages

- With `rankPages` set, the player needs one of the rank nodes; without a match they are limited to `defaultPages`.
- The next page needs a price in the list that is used (`defaultCosts` or the provider list).
- `/ksbank upgrade` always uses `defaultCosts`, while the Pages tab may use a provider list.

### Players get the wrong rank pages

Rank nodes are checked through LuckPerms when it is installed, otherwise through Hytale's own permission system. Check which of the `rankPages` nodes the player really has; the highest value of those wins.

### My changes to `config.json` have no effect

Look for `config.json cannot be read (...)` in the log, or run `/ksbank reload`: "Error loading config: ..." names the problem (usually a JSON syntax error). The bank never changes such a file; it keeps running on the settings it had (the built-in defaults after a start). Fix the file and run `/ksbank reload` again. See [Configuration](./configuration#validation).

### The history is empty

The history lives in `bank.db`. If the log shows `Failed to initialize database`, check that the data folder is writable. The History tab then shows "No transactions yet".

### `Skipping pack at kyuubisoft_bank: missing or invalid manifest.json`

Harmless. Hytale checks every folder in `mods/` for an asset pack, and the bank's data folder is not one.

### What are the items "Previous Page", "Next Page", "Page Info" and "History"?

`Bank_Prev`, `Bank_Next`, `Bank_Page` and `Bank_History` are navigation items of the old bank window. The jar still contains them (with their texts in all 9 languages); 2.6.6 does not use them.