Skip to content
KyuubiSoft Wiki
News & Patchnotes

FAQ & Troubleshooting

FAQ & Troubleshooting

Section titled “FAQ & Troubleshooting”

Setup

Section titled “Setup”

”No economy provider detected” in the log

Section titled “”No economy provider detected” in the log”

Provider mod (Ecotale, etc.) registers with VaultUnlocked after Shops finishes loading. The plugin auto-retries detection at +2s, +5s, +10s, +20s. Look for Economy provider attached on retry in the log.

If still missing after 20s:

  • Verify the provider mod is actually installed in <server>/mods/
  • Check the provider’s own log for registration errors
  • Verify VaultUnlocked is installed (TheNewEconomy:VaultUnlocked)

Could not find document Pages/...ui for Custom UI Append command

Section titled “Could not find document Pages/...ui for Custom UI Append command”

A Hytale silent-parse-failure: one .ui file in the load queue has a syntax error, the loader aborts, and the error names whatever file was queued next - not the broken one.

Check the most recently changed .ui file. Common culprits:

  • LayoutMode: LeftCenter - not valid. Use LayoutMode: Left + VerticalAlignment: Center on children.
  • HorizontalAlignment: Left / Right - not valid. Use Start / End.
  • Anchor: (CenterX: ...) - not valid. Use Left + Right + Width.

Valid LayoutModes: Top, Left, Center, CenterMiddle, TopScrolling, LeftCenterWrap, Full.

Slot UI shows missing-texture X

Section titled “Slot UI shows missing-texture X”

BankSlot.png was missing from the JAR. Should be bundled now (Common/UI/Custom/Pages/Bank/BankSlot.png in the resources). If you see X marks: rebuild + redeploy with ./gradlew :mods:shops:build :mods:shops:deployToServer and restart.

Permissions

Section titled “Permissions”

Player gets “Du hast keine Berechtigung dafür” on /ksshop create

Section titled “Player gets “Du hast keine Berechtigung dafür” on /ksshop create”

LuckPerms ignores the plugin’s default = true argument. Grant explicitly:

lp group default permission set ks.shop.user.create true

See Permissions for the full setup.

OP can create unlimited shops despite maxShopsPerPlayer = 3

Section titled “OP can create unlimited shops despite maxShopsPerPlayer = 3”

OP / wildcard * matches ks.shop.limit.shops.200 etc. The plugin’s wildcard sentinel should catch this and fall back to the config default. If it’s not catching, check that you’re not using the legacy resolve path - rebuild from latest source.

Listing shows “permanent” on every new shop

Section titled “Listing shows “permanent” on every new shop”

Same wildcard issue: OP matches ks.shop.list.permanent. The wildcard sentinel should treat this as “no specific grant” and follow the listing-on-create rules. If it’s not, check the hasExplicit call site in ShopService.createPlayerShop.

To grant ks.shop.list.permanent to a specific OP intentionally:

lp user <admin> permission set ks.shop.* false
lp user <admin> permission set ks.shop.list.permanent true

Commands

Section titled “Commands”

”Wrong number of required arguments” on /kssa createrental

Section titled “”Wrong number of required arguments” on /kssa createrental”

Hytale validates arg count against the declared list before execute runs. Optional args must be declared via withOptionalArg to be accepted positionally. All current rental + transfer + delete commands use this pattern.

If you hit this on a custom-added command, switch from parts[] parsing to withOptionalArg + ctx.get(arg).

/ksshop transfer X Y confirm -> --confirm=confirm syntax error

Section titled “/ksshop transfer X Y confirm -> --confirm=confirm syntax error”

Old behaviour. Replaced with subcommand handshake:

/ksshop transfer X Y                  -> sender stages a request
/ksshop accepttransfer                -> target opts in
/ksshop declinetransfer               -> target rejects

Unknown command: /ksshop

Section titled “Unknown command: /ksshop”

Player joined the server before the plugin loaded. Hytale caches the command list per session.

Fix: have the player close and rejoin the client.

Shops & NPCs

Section titled “Shops & NPCs”

NPC spawns 1 block off after force-expire / server restart

Section titled “NPC spawns 1 block off after force-expire / server restart”

Was a known bug - the lazy-spawn path used calculateNpcPosition with a 1.2-block offset along the NPC’s rotation (legacy from the Shop_Block era). Fixed in the current code - the lazy-spawn path now uses shop.getPosX/Y/Z directly.

If it recurs, check spawnNpcInternal is not calling calculateNpcPosition.

NPC has no skin (default grey model)

Section titled “NPC has no skin (default grey model)”

The owner-name lookup hit a transient PlayerDB error. The plugin retries once after npc.skinRetryDelaySeconds (default 5s). If still nothing:

  • Verify the username exists at playerdb.co/api/player/hytale/<username>
  • Set npc.defaultSkinUsername = "Notch" (or any real Hytale user) as a global fallback
  • Check the in-memory + on-disk cache: <server>/mods/kyuubisoft_shops/skin-cache.json

NPC despawned and never came back

Section titled “NPC despawned and never came back”

Run /kssa respawnnpcs in the affected world to force a sweep + respawn from persisted shop data. Recovers from chunk-restored ghost NPCs without a server restart.

Force-expire leaves no NPC at the slot

Section titled “Force-expire leaves no NPC at the slot”

Should auto-respawn the vacant shell NPC inline. Fixed in the current code. If not, run /kssa respawnnpcs once.

Slot UI shows wrong slot positions in browse

Section titled “Slot UI shows wrong slot positions in browse”

By design now - items render at the exact slot the owner placed them in the editor. Slot 10 in editor stays slot 10 for buyers. This is a feature, not a bug.

Listings & directory

Section titled “Listings & directory”

Shop is in /ksshop myshops but not in /ksshop browse

Section titled “Shop is in /ksshop myshops but not in /ksshop browse”

myshops is owner-only and ignores the listing filter (so you can find a delisted shop to extend). browse filters by isListedInDirectory() - returns true only if listed_until > now or Long.MAX_VALUE.

If the shop’s listing has expired:

  • /ksshop list <days> to extend it
  • Or buy/extend via the editor Settings tab Directory Listing block

”Free listing days on create” was given twice

Section titled “”Free listing days on create” was given twice”

Should not happen - the flag persists in shop_player_flags table and survives delete + recreate. If you see it twice for the same player, check shop_player_flags.free_listing_used for that UUID. Set to 1 manually if needed.

Rentals & auctions

Section titled “Rentals & auctions”

Auction stays “Auction not active” after a rental ends

Section titled “Auction stays “Auction not active” after a rental ends”

Check rentalStations.onEmptyAuction. If VACANT or DELETE, the auction is not auto-rearmed. Set to RESTART (default).

To re-arm an existing slot manually: delete + recreate, or DB-edit auction_ends_at (server stopped).

”Time Remaining: 0s” on an active auction

Section titled “”Time Remaining: 0s” on an active auction”

Server time has passed auction_ends_at but the scheduler tick hasn’t finalised yet. Will resolve within 60s.

If it stays at 0s longer: scheduler isn’t running (check log for RentalExpiryTask: finalized N expired rental(s) - should appear roughly every 60s when there’s work).

DB edit on rented_until doesn’t take effect

Section titled “DB edit on rented_until doesn’t take effect”

The plugin caches RentalSlotData in memory. Live DB-edits don’t sync back, and the next auto-save (every 60s) overwrites your edit.

Always: stop server first, edit DB, start server. Or use /kssa forceexpirerental <slotId> for live testing.

Renter sees “60 days” remaining on a freshly won auction with maxDays=7

Section titled “Renter sees “60 days” remaining on a freshly won auction with maxDays=7”

The slot was created with maxDays=60, not maxDays=7. Check the /kssa createrentalauction arg order:

/kssa createrentalauction <displayName> <minBid> <bidIncrement> <durationMinutes> <rentalDays>
                          MarketSlot      500     10             60                7
                                                                 ^ minutes (auction)
                                                                                   ^ days (rental)

Fix: /kssa deleterental <id> + recreate with correct args.

Bidder sees “1d 0h” but maxDays = 7

Section titled “Bidder sees “1d 0h” but maxDays = 7”

Probably looking at a refresh-stale UI. The bid page shows Rental Period: 7 day(s) if you win from slot.maxDays. If it shows 1, your slot has maxDays = 1.

Rental shop nameplate shows wrong remaining time after DB edit

Section titled “Rental shop nameplate shows wrong remaining time after DB edit”

The nameplate reads from RentalSlotData.rentedUntil (source of truth) at spawn / refreshNameTag time, not live-tickling. After a DB-edit-with-restart, the remaining time should be correct on next render.

If you only edited shop_shops.rental_expires_at (the mirror) and not the slot row, the display will lag - mirrors are read in some fast-paths but the source-of-truth is the slot.

Editor

Section titled “Editor”

/ksshop edit -> “Failed to open the shop UI”

Section titled “/ksshop edit -> “Failed to open the shop UI””

The editor lock is held by another session. Check /kssa admin Players tab for active sessions, or have the other player close their editor. If stuck, restart the server.

Editor saves but items vanish

Section titled “Editor saves but items vanish”

Check the staging snapshot - the editor takes a snapshot at open time and only commits NEW staging items (vs original). If you remove items from the shop grid and don’t re-add them, they go to mailbox via the standard refund flow.

/ksshop deposit X -> Shop balance unchanged

Section titled “/ksshop deposit X -> Shop balance unchanged”

Verify the shop is your own (getShopsByOwner filter) AND in the same world. The command operates on the nearest owned shop in your current world.

Performance

Section titled “Performance”

Server lags when many players join

Section titled “Server lags when many players join”

NPC spawn burst on first-player-in-world. Increase npc.spawnDelaySecondsOnJoin to 5-10s on busy servers - gives the client time to set up before skins push.

Browse page is slow with 200+ shops

Section titled “Browse page is slow with 200+ shops”

DirectoryService.searchShopsFiltered does a linear scan + sort. For very large servers, consider:

  • Tighter filters in browse (Featured tab, category filter)
  • Lower directory.shopsPerPage to 6 to reduce render cost

A planned future improvement: backing-index for hot-path queries.

Where to file bugs

Section titled “Where to file bugs”

GitHub issues at the ks-shops repo. Include:

  • Server log around the failure (10 lines before + after)
  • Config snippet if config-related
  • Steps to reproduce
  • Hytale server version

The plugin’s CHANGELOG tracks all fixes - check there first to see if your issue is already addressed.