Shopkeepers tasks
Task guides and troubleshooting for Shopkeepers. Check the installed release before changing configuration or data.
- Fix a Shopkeepers trade blocked by a full payment chest
- Test Shopkeepers buying trades with enchanted and damaged items
- Change one Shopkeepers price without altering the item being sold
- Explain why a Shopkeepers trade ignores a Vault money balance
- Avoid title collisions in a Shopkeepers book shop
- Investigate a Shopkeepers container link that an owner cannot use
- Back up Shopkeepers records together with shop containers
- Separate Shopkeepers owner editing from customer trading
Fix a Shopkeepers trade blocked by a full payment chest
A player shop needs space to receive payment as well as stock to sell. A chest full of sale items can prevent a valid trade even when the customer holds the correct currency.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Ask the owner to open the linked container and record which slots hold sale stock and which can accept the configured payment item.
- Inspect the exact trade costs in the editor, including quantities and any custom currency item metadata.
- As a normal customer, try one inexpensive trade while the owner watches the stock container, then note whether either side changes.
- Move a small amount of the owner’s stock to a safe labeled container to leave payment space and repeat the same trade without changing its price.
Confirm the result
The trade should complete once enough matching stock and sufficient payment space are available. The customer receives the advertised item and the linked container receives the exact currency items.
If the result differs
A free slot may still be insufficient for a large payment or an unstackable custom currency. If space is adequate, compare the payment item’s metadata and the offered quantity with the recipe.
Recover safely
Return the temporarily moved stock after arranging permanent payment capacity. Do not replace the entire chest or delete the shop, because that can separate ownership and stock from the existing trade record.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Test Shopkeepers buying trades with enchanted and damaged items
Buying shops need careful item matching. Vanilla trade behavior can accept or reject variants in ways an owner did not expect, so test valuable equipment before advertising a buy offer.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Record the buying recipe, including the example item and currency quantity, and use an isolated shop stocked only for a few low-value tests.
- Prepare separate plain, damaged, enchanted and renamed samples relevant to the item, labeling their differences outside the trade inventory.
- Try each sample with a normal customer account and record which variants the current release accepts; inspect the resulting item in the owner’s chest.
- Check the maintainer’s buying-shop matching notes before changing the example item. Avoid assuming every name or enchantment creates a strict distinction.
Confirm the result
You should have a written acceptance matrix for the recipe before using it with expensive player items. Each accepted variant must produce the intended payment and reach the owner’s container.
If the result differs
Vanilla matching can be asymmetric: a plain requirement may accept a more decorated item. A visual preview alone does not prove that enchanted or cursed equipment is excluded.
Recover safely
Disable the affected offer through the supported editor until its acceptance rules are suitable. Preserve original sample items and restore the previous recipe rather than deleting the shop or its container.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Change one Shopkeepers price without altering the item being sold
The trade editor changes both recipe contents and quantities. Make a narrow price edit so an owner does not accidentally replace a custom sale item while adjusting its cost.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Have the owner record the existing trade’s result item, amount, both cost slots if used, and enough stock for one transaction.
- Open the supported shop editor as the owner and change only the intended cost or quantity using the controls documented for that release.
- Close and reopen the editor to verify the saved recipe, then inspect the customer trade screen from a separate normal account.
- Complete one low-value trade and compare the delivered item’s metadata, stock reduction and payment increase against the recorded values.
Confirm the result
Only the intended price should change. The sold item, shop ownership, container link and unrelated offers should remain the same after reopening the editor.
If the result differs
If the displayed recipe differs between owner and customer, close both interfaces and check server logs for a plugin conflict. Do not repeatedly edit while a customer holds an older trade screen.
Recover safely
Restore the recorded recipe through the editor if either cost slot or result item changed unexpectedly. Reimburse the controlled test separately instead of guessing how many historical trades used the new price.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Explain why a Shopkeepers trade ignores a Vault money balance
Shopkeepers player shops normally exchange physical items. A customer’s economy balance does not supply the item cost shown in a villager-style trade, even when Vault is installed on the same server.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Open the customer trade screen and identify the actual cost item, its quantity and any second cost slot.
- Check the owner’s configured shop type and its stock container so the recipe is understood as an item exchange rather than a cash withdrawal.
- Give a normal test account only the exact low-value cost item and enough free inventory space, then record its separate Vault balance.
- Complete one trade and compare the item inventory, container contents and unchanged economy balance before documenting payment instructions for customers.
Confirm the result
The trade should consume matching currency items and deliver the result without changing the Vault balance. A customer with money but no required items should not complete that same recipe.
If the result differs
A separate integration or custom shop type may add different behavior, so list installed extensions before assuming standard rules. Do not install another economy bridge merely to make a physical-item recipe accept money.
Recover safely
Keep the existing recipe while clarifying its payment wording. If you require cash sales, test a documented compatible integration separately and retain the current shop and container until a migration is planned.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Avoid title collisions in a Shopkeepers book shop
Book shops copy an owner’s written books using the documented book-shop rules. Reusing titles can make stock identity confusing, so establish a small controlled catalogue before opening a large library.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Read the book-shop section for your installed release and record the written book’s title, author and generation before using it as a sample.
- Give each intended catalogue entry a distinct title and keep an untouched original outside the shop container.
- Stock the linked container with the required copying materials described by the maintainer, then offer a low-value test copy to a normal customer.
- Inspect the purchased book’s pages, title and generation and compare the container changes with the expected copy process.
Confirm the result
The customer should receive the intended readable book while the shop retains the correct catalogue entry and consumes the documented materials. Another book should not be substituted because its title collides.
If the result differs
Copy-generation restrictions or unsuitable stock can block a trade even when a book looks correct in the preview. Check those details before changing permissions or rewriting every catalogue entry.
Recover safely
Remove the affected offer through the editor until its identity is clear, preserving the original books and container contents. Rebuild only that catalogue entry from the untouched original when repeating the test.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Investigate a Shopkeepers container link that an owner cannot use
A shop entity, its owner and the linked container must agree. Diagnose that relationship before moving chests or giving every nearby player permission to open protected storage.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- Record the shop owner, shop type and precise container location, then check whether the owner can access the container directly.
- Read the installed release’s player-shop setup requirements for valid containers and linking distance rather than assuming a nearby chest is the actual stock source.
- Check claim or region permissions with a normal owner account and confirm that only intended staff can edit the shop.
- Try one inexpensive customer transaction while monitoring the identified container, looking for the expected stock and payment change.
Confirm the result
The owner should be able to manage the intended stock source, while customers can trade without receiving general access to that container or permission to edit offers.
If the result differs
A region plugin can block interaction independently of Shopkeepers ownership. A second nearby chest receiving stock is evidence of a mistaken link, not a reason to disable protection across the market.
Recover safely
Restore the previous narrow protection setting if the trial exposes storage. Preserve the original container and shop record until the documented relinking process has been tested with a copy.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Back up Shopkeepers records together with shop containers
Saving only a plugin file does not preserve the world containers holding player stock. Take a consistent checkpoint before a world move, plugin update or ownership repair.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- List the worlds containing shop entities and their linked containers, and locate the plugin data directory documented for your server platform.
- Pause trading during the checkpoint and save the worlds using the server’s supported procedure; use a clean stop if a consistent running backup is not supported.
- Back up the world data and matching Shopkeepers data together, recording the server and plugin builds beside the archive.
- Restore into an isolated test server and check owner editing, stock quantities and one inexpensive customer trade before relying on the checkpoint.
Confirm the result
The restored test should contain the shop entity, correct owner, linked container and matching inventory from the same checkpoint. Its trades must not connect to live shared storage accidentally.
If the result differs
A backup that restores entities without stock is incomplete for player shops. If records and worlds were captured at different times, preserve both copies and investigate rather than merging ownership by guesswork.
Recover safely
Keep the original checkpoint immutable. Restore the matching complete dataset on the isolated server when repeating tests, and do not overwrite newer production trades with an older shop file.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.
Separate Shopkeepers owner editing from customer trading
A customer should be able to trade without editing recipes or handling stock. Test those boundaries with real player roles so an administrative bypass does not hide an access mistake.
Before you start
Shopkeepers player trades exchange physical items held in a linked container. A Vault balance is not the stock for these trades. Work with the shop owner and keep the container, shop record and item metadata together when investigating a failure.
Work through the check
- List the owner and any supported staff roles for one test shop, then record claim permissions for its stock container.
- Open the editor as the actual owner using the documented interaction, keeping the trade configuration unchanged during the access check.
- Use an unrelated normal account to open the customer screen, attempt an inexpensive trade and confirm it cannot open the editor or stock chest.
- If an extension manages staff access, check its documented scope separately; do not assume a generic claim trust grant is limited to this shop.
Confirm the result
Customers should trade through the offered recipes while only authorized owners or documented staff can change them. Container protection should stay independent of the customer trading permission.
If the result differs
An operator or region bypass can make a failed protection test appear successful. Recheck with fresh normal accounts and inspect inherited permissions before changing Shopkeepers settings.
Recover safely
Remove only the accidental editing or storage grant if the test account gains excess access. Preserve shop ownership and offers; deleting the shop is not needed to correct a permission boundary.
Documentation and related help
Check the Shopkeepers maintainer documentation and Shopkeepers maintainer reference against your installed release before applying changes.