# FAQ & Troubleshooting

**Version:** 2.0.6

## Setup

### "No economy provider detected" in the log

The plugin uses KyuubiSoft Core's economy bridge or VaultUnlocked with a registered provider (for example Ecotale). Providers that register late are picked up by checks 2, 5, 10 and 20 seconds after the start; look for `Economy provider attached on retry`. If it never appears, the provider is missing or does not register with VaultUnlocked; check its own log. Without an economy nothing can be bought, sold, rented or opened.

From 2.0.7 (not released yet) a late economy is also found by the next shop action (`Economy provider attached when a shop needed it`). A server without any economy plugin can switch on [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/), the server currency of KyuubiSoft Core 2.10.0; Shops pays with it through Core.

### `/ksshop` only prints a list

`/ksshop` and `/kssa` without a subcommand print their subcommands. The market opens with `/ksshop browse`, the admin window with `/kssa admin`.

### My translation changes are gone after the update

Language files older than the current version (32 since 2.0.3) are saved as `<lang>.json.backup-v<old>` and replaced. Copy your changes from the backup into the new file and run `/kssa reload`. See [Configuration](./configuration#localization).

### A server shop from a template lost its in-game changes

On the first start of 2.0.0 every enabled template file rewrites its shop once, because no applied version was recorded yet. After that a template only rewrites its shop when the file changes. See [Server shop templates](./configuration#server-shop-templates).

---

## Opening shops

### The license dialog does not let me open a shop

The button says why:

| Button | Cause |
|--------|-------|
| "Limit reached" | You own as many shops as your limit. Packed shops count, shops on rented stands too unless `rentalStations.rentalShopsCountTowardShopLimit` is `false`. Delete or set up a packed shop, end a rental, or get a higher `ks.shop.limit.shops.N` |
| "Check name" | The name is too short, too long or already used by another shop (names are unique on the whole server, not case-sensitive) |
| "Not enough money" | Your wallet does not cover `playerShops.creationCost` |

Other refusals show in the red box: "Player shops are currently disabled on this server." (`features.playerShops`), "The economy system is unavailable." (no economy), "You can only create shops on land you have claimed." (with `playerShops.requireClaim`: you stand in someone else's claim), "You no longer carry a business license.".

### Do I need the license?

The license dialog is the intended way. `/ksshop create <name>` opens a shop without a license as well (same cost and limits); both need `ks.shop.user.create`.

### Can I move my shop?

Pack it up in the editor (**Shop** tab → **Pack up the shop**). You get a license back that is bound to this shop; use it where the shop should stand and pick "Set up ... here". Name, rating, settings and history stay; fetch the stock from your mailbox and restock. Shops on rental stands cannot be packed up.

---

## The market

### My shop is not in the market

The market lists open, unpacked shops. Player shops only while their listing runs:

- Your first shop ever gets `listingFreeDaysOnCreate` (7) free days once; later shops start unlisted.
- Buy or extend the listing in the editor (**Shop** tab → **Market listing**) or with `/ksshop list <days>`.
- A closed or packed shop is never listed. Packing up does not stop the listing's end date.

Unlisted shops can still be visited at their merchant or with `/ksshop visit <name>`.

### I switched "Market listing costs gold" off, but old shops are still missing

Switching listings off only makes **new** shops permanently listed. Shops that were unlisted at that moment stay unlisted, and with listings off nobody can buy a listing for them. Switch listings on, let the owners list their shops (or give them `ks.shop.list.permanent` and let them buy a listing once, which makes it permanent), then switch it off again.

### What does "Most sales" sort by?

By the shops' total revenue.

### Why does an offer say "This offer just changed"?

The owner changed the item or the price of that slot after your list was shown. Check the new price and buy again.

---

## Trading and the mailbox

### Where are the items I bought?

In your mailbox (unless the server turned on `mailbox.deliverPurchasesToInventory`, then in your inventory with the rest mailed). Craft a Mailbox at the Carpentrybench (4 Oak Planks + 1 Iron Bar), place it and press **F**. Every mailbox block shows the same mailbox.

### I cannot claim from `/ksshop notifications`

That window is view only. Claiming only works at a Mailbox block.

### Claiming says "No room in your inventory"

Items are only taken out as far as they fit; the rest stays in the mailbox. Make room and claim again. Gold is always paid out in full.

### Where is the money from my sales?

Each sale creates a money mail in your mailbox ("Steve bought at Food Corner"), or one growing mail per shop with `mailbox.combineSaleEarnings`. The till only holds the gold you deposited for buybacks.

### The Sales tab is empty although I sold things

The Sales tab only lists sales that happened while you were offline. The money mails on the Claim tab are there either way.

### The shop does not take my item

On the **Sell** tab the detail lists the limits; the one in amber decides. Possible reasons:

- The shop does not buy this item (buyback off), or its buyback quota is used up (the shop stops buying it).
- Your item is damaged, or has other enchantments or metadata than the shop's offer. Only exact matches count as "You have".
- "Room in the shop": the shop reached its "stop buying at stock" value.
- "Till covers": the owner's till is empty or too low.
- It is your own shop.

### Who pays the taxes?

With taxes on: buyers pay the buy tax on top of the price; players selling to a shop lose the sell tax from their proceeds. Taxes are rounded to whole gold and leave the economy.

---

## The editor

### "This shop is currently being edited by another session."

Only one person can have a shop's editor open. The lock is released when that window closes. As the owner, **F** on your merchant opens the shop window instead while someone else edits.

### My new offer is not for sale

New offers start with a price of 10 and are not live until you press **Save** on the Offer tab. Their slot tooltip says "Not live yet".

### The editor refuses an item

"Damaged items cannot be sold", "This item cannot be sold in shops" (blacklist), "Another version of this item is already in the shop" (one offer per item ID; a stack with other enchantments is a different version), "You can offer at most N different items" (`ks.shop.limit.items.N` / `maxItemsPerShop`), "The shop is full (45 slots)".

### My changes are gone after closing the editor

Prices, limits, name, description, category and icon are drafts until **Save**. Closing discards them; the chat says how many. Moving items, open / closed, the merchant look, the name tag, the listing and the till apply at once.

### There is no Withdraw button

Taking gold out of the till is off by default (`playerShops.allowBuybackWithdraw`). The till comes back when you pack the shop up.

### What do I get back when I delete a shop?

`/ksshop delete` mails stock and till to you and pays half of the current `creationCost` back.

---

## Merchants

### A merchant has the default look instead of a skin

Skins are looked up by player name at `playerdb.co`. A failed lookup is retried once after `npc.skinRetryDelaySeconds`. Check the name in the editor's **Merchant** field, set `npc.defaultSkinUsername` for shops without a look, or wait for the next spawn. Skins are cached in `skin-cache.json`.

### A merchant is missing or there are two

Run `/kssa respawnnpcs` in that world: it respawns the merchants of every shop there (player shops, rented and free stands, server shops; packed shops have none) from the saved data and removes leftover copies. `/kssa openplayer <shopId>` spawns a missing merchant of a single shop (and opens the shop). Merchants that could not spawn (chunk not loaded yet) are retried automatically every 30 seconds, in the default world and in every world where shop merchants were spawned.

### A merchant stayed after pack-up, delete or the end of a rental

Merchants are removed in their shop's own world, also outside the default world: after pack-up, delete, the end of a rental, stand changes and at shutdown. A sweep every 30 seconds removes leftover copies in every world with shop merchants. If one still stays, run `/kssa respawnnpcs` in that world.

### The closed shop still talks to me

Closed shops only answer their owner (who gets the editor). Everyone else gets "This shop is currently closed.".

---

## Rental stands

### An auction does not start again after a rental

Only with `onEmptyAuction: RESTART` does an auction stand start a new round when a rental ends. With `VACANT` (or `DELETE`) it rests; press **Restart auction** in the admin window (**Rental stands**).

### "Your win of ... was forfeited"

The winner did not have the bid in their wallet when the auction ended. All bids are cleared and a new round starts.

### I cannot extend my rental

Stands won at auction cannot be extended. Fixed-price rentals extend by up to `extendMaxDays` per click in the market's **My shops** tab.

### Where does my rented shop appear?

Always at the stand, in the stand's world, wherever you were when you rented or when the auction you led ended. If that world is not loaded at that moment, the merchant appears when it loads.

### A stand's merchant stays although the stand is gone

With `onEmptyAuction: DELETE` the placeholder shop and its merchant are now removed with the stand. A placeholder left behind by an earlier version counts as a server shop: delete it with `/kssa deleteadmin <shopId>` or in the admin window's **All shops**. See [Rental Stands](./rentals#when-the-auction-ends).

---

## Permissions

### An operator gets only the default limits

A wildcard (`*`, `ks.*`) is detected and the limit and listing nodes then fall back to the config values, so operators do not get 200 shops or free permanent listings. Raise the config values, or give staff accounts without a wildcard explicit `ks.shop.limit.*` nodes. See [Permissions](./permissions#wildcards).

### A limit node does not lower the limit

The config value is the floor; `ks.shop.limit.shops.N` can only raise it.

---

## Common problems

| Problem | Cause | Solution |
|---------|-------|----------|
| "You don't have permission to do this." | A `ks.shop.user.*` node is set to `false` | These are allowed by default; check your permission plugin |
| "The shop directory is disabled on this server." | `features.directory` is `false` | Switch "Market active" on in the admin window |
| "Shop notifications are currently disabled on this server." | `notifications.enabled` is `false` | Set it to `true` |
| "You don't have any shops." on `/ksshop edit` | None of your unpacked shops is in your current world | Go to the shop's world or use **Manage** in the market |
| Rental stands tab missing | `rentalStations.enabled` is `false` | Switch it on and restart |
| A stand's name plate says `[100g/day]` with your currency being something else | The free stand name plate is not translated | Cosmetic |