Known Issues

This list documents differences between different Minecraft/Spigot versions, as well as known issues and incompatibilities with other plugins or server software.

Currently supported Minecraft versions (1.21.x, 1.20.x, 1.19.4, 1.18.2, 1.17.1, 1.16.5):

• Older Bukkit/Spigot versions: Testing is primarily done with the latest version. If you encounter any problems with older server versions, let me know and I will look into it. Also note that migrating from a newer server version back to an older one is not supported and will likely corrupt Shopkeepers' save data. Always make backups when you update your server version.
• Unsupported mob types: Some entity types can be enabled inside the config for experimental use, but might cause all kinds of issues. Only the by default enabled mob types are officially supported. See the changelog of v1.50.
• Peaceful difficulty: On peaceful difficulty the server will instantly remove any monster shopkeepers again right after the plugin spawns them.
• Written book trades: If the trade for a written book fails, players can sometimes still open and read the book if they close the shop and click the temporary fake book in their inventory fast enough. There is not much I can do about this.
• MC-89883: Squids and glow squids can be pushed around.
• Minecraft migration debug messages: Minecraft may log 'Unable to resolve BlockEntity for ItemStack ...' messages during ItemStack migrations. You can safely ignore these debug messages.
• Player head items: When you create a player head item with a SkullOwner name, eg. like this /give @p player_head{SkullOwner:"MHF_Chest"} 1, Minecraft eventually fetches the profile for the player with this name and then replaces the SkullOwner of this item with the full profile. This profile then contains information such as the texture of the player head item. However, there is no guarantee as of when the SkullOwner of the item is replaced with the full profile. Some inventory actions may trigger this conversion, as well as when the item is saved and loaded by Minecraft. But as long as the SkullOwner profile has not yet been set for the item, it may not be reliably useable in shopkeeper trades.
  As a player, you also cannot easily differentiate between an item that already had its SkullOwner replaced with the profile versus one that is still pending: The item may appear to already have the intended texture, even though it has not actually been saved yet into the item.
  Another related issue is that the fetched player profile not only contains the player's texture, but also a timestamp of when this profile was fetched. Minecraft caches the fetched profiles in the server. So as long as this cache still contains the profile, this timestamp will be the same for all created items. However, this cache is periodically wiped. If Minecraft has to freshly fetch the profile again for a newly created item, its timestamp will be different and then item will no longer match items that have been created previously. This difference in their internal data not only causes newly created items to not stack with previously created items, but also prevents to trade them in shopkeepers.
  The only real solutions currently seems to be to either specify the full profile (UUID, texture, timestamp, etc.) when you create the player head item via command, or create the item only once, store it somewhere, and then use it as a template to create copies of it (for example in creative mode) later on when you want to create new items of this type. If the item already contains a complete and valid profile, Minecraft will not change it, even if the player happens to change his texture in the meantime (reference: https://bugs.mojang.com/browse/MC-52806).
  This same issue may also affect plugins that create player head items: If they don't specify the full profile but only the player name, the server has to fetch the profile at some point.
• Spigot: If you are using Spigot and you have many villagers in one place, consider disabling the Spigot setting tick-inactive-villagers: Having this enabled may keep chunks with many villagers loaded indefinitely.
• SPIGOT-6949: In some versions since 1.18.1, Spigot made some changes to how configs are saved and loaded in order to better support the persistence of config comments. However, these changes broke the serialization of config sections that are nested in lists or maps. This affects the saving of Citizens NPC shopkeeper snapshots, since the NPC data is represented as a nested config section withing the list of snapshots. Any saved NPC data is lost, and will also prevent the save file from loading.
• GH-886, SPIGOT-7676: In some versions of Spigot before 1.20.6 (noticed in 1.20.4), users with the turkish locale ran into an issue with the Shopkeepers plugin not starting due to "failed server assumption tests". The issue was caused by the Spigot server not properly accounting for the turkish locale and its special rules regarding upper and lowercase i characters when doing certain text conversions that are for example relevant to properly persist certain item enchantments in the Shopkeepers plugin's save data. The issue has been fixed in some version of Spigot for MC 1.20.6. For older server versions, the workaround is to start the server with the parameters -Duser.language=en -Duser.region=EN.
• Paper:
  • To prevent sign shopkeeper blocks to get persisted with the world/chunk data (so that all shopkeepers are gone if you decide to no longer use the plugin, or in case of server crashes), the plugin removes all shopkeeper sign blocks from the world prior to world save and respawns them again 1 tick afterwards. Paper has a feature which performs the actual saving of chunks incrementally across more than 1 tick, so the saving won't be complete when Shopkeepers respawns the sign shopkeepers. The consequence of this is that these sign blocks might end up still being present in the world if you decide to no longer use the plugin, or if the server crashes.
  • Paper serializes and deserializes Minecraft's CanDestroy and CanPlaceOn item tags differently compared to Spigot. The result is that any items stored by the Shopkeepers plugin (eg. items in shopkeeper trades) might lose these tags when you switch between Paper and Spigot back and forth. Relevant Paper ticket: https://github.com/PaperMC/Paper/issues/6689
    They decided to only fix one side of the issue: When switching from Spigot to Paper, Paper will now import these tags from Spigot. However, the same issue still applies when you decide to switch from Paper back to Spigot, or when you transfer the data of saved items or shopkeepers from a Paper server to a Spigot server. But this does not seem to be something they want to support. Example scenarios in which this can occur is when you test if some issue that you experience on your Paper server also affects the Spigot server, or when you exchange your shopkeeper save data with someone else that happens to run a Spigot instead of a Paper server.
  • Paper's ItemMeta implementation stores the CanDestroy and CanPlaceOn tags of items in an unordered HashSet, whereas Minecraft stores them in a List. Conversions of Minecraft items to this Bukkit representation and back to Minecraft items (as they occur in various situations, including when Shopkeepers saves and loads these items) might not preserve duplicate tags or the order of these tags. This can potentially result in the items before and after this back and forth conversion to not be considered equal by both Minecraft and the Shopkeepers plugin, and consequently resulting in item stacking and trading issues.
  • Configuring very small values in the item-validation section of the paper-global.yml can result in issues due to the server then truncating certain item data in certain situations. This can also result in the plugin's "server assumption tests" to fail during startup and the plugin refusing to enable.
• ClearLagg (checked version 3.0.6): ClearLagg's 'chunk-entity-limiter' prevents mobs (even plugin-spawned mobs) from spawning if a certain limit of entities is reached within the chunk. Since ClearLagg prevents entity spawning on MONITOR priority, it is impossible for Shopkeepers to bypass this. Various other features of clearlag might periodically remove the Shopkeeper entities as well. However, the Shopkeepers plugin should periodically attempt to respawn missing shopkeeper entities. Using any features of ClearLagg that attempt to unload chunks or limit chunk loading might interfere with Shopkeepers as well. Reference: https://github.com/Shopkeepers/Shopkeepers/issues/587
  On later versions of ClearLagg, it should be possible to configure it to ignore entities with custom meta data (such as mobs spawned by Shopkeepers).
• Ultimate_Economy: This plugin seems to incorrectly treat Shopkeepers' editor inventory views as its own custom inventory views (due to having 'editor' in the view title), making it impossible to click anything inside the shopkeeper editor view and thereby prevents setting up any trades. For reference: https://www.spigotmc.org/threads/ultimate_economy.331584/page-10#post-3540110
• MythicMobsExtension: The version available on Spigot (currently v1.239) somehow causes the shopkeeper trading and editor views to instantly close again (tested on MC 1.15.2). This plugin version seems to be outdated (also produces various errors inside the log). Newer versions are available here (linked from their official Github page). I tested with a snapshot of v1.557 and am not able to reproduce the issue there.
• Moneynote: In order to get Moneynote items to work inside Shopkeeper trades you will need to disable their glow effect, disable reject-villager-trading, and remove the %signer% line from the item's lore. If you are on MC 1.8.x you need to use Shopkeepers v2.2.3 (available on the Discord server, pinned in channel announcements).
  Since the 1.16 update (I don't know which version; I checked v1.3.1), Moneynote adds an attribute to each created item and gives it a random UUID (https://prnt.sc/tq7bzm). On earlier versions this UUID would be the same for each created item. This breaks any trading of these items, since their internal UUIDs will likely not match. Ref: https://www.spigotmc.org/threads/moneynote-convert-digital-money-into-paper.333126/page-3#post-3895977
  The UUID issue might have been fixed in v1.3.3, but I haven't tested this.
  In some versions of this plugin (I checked v1.4) the included default config is empty. So you may have to manually insert these settings:

use-static-uuid:
  enabled: true
  do-not-edit-this: '7d6f11b6-86c4-4c66-891c-9f1ae6a70fdb'

• GriefPrevention + GeyserMC: A user reported that Bedrock players were not able to edit their player shopkeepers. But trading with the shopkeeper still worked fine. Additionally, once a player tried to open the shopkeeper editor, they were not able to open any other inventory anymore either (such as the inventory of chests), until the player rejoined the server. It turned out that this issue only affects player shops in regions protected by GriefPrevention to which the shop owner is only 'trusted'. Additionally executing /permissiontrust {player} for the shop owner somehow resolves the issue. The used server version was 1.17 and the Shopkeepers version was v2.13.0.
  Another user tracked down the issue to opening the trading interface for shopkeepers that have no offers yet (https://github.com/Shopkeepers/Shopkeepers/issues/756). I am not aware whether or not the previous description is therefore void. v2.13.2 will no longer open the trading interface for shopkeepers without offers.
• OpenInv: Some plugins provide a sort of 'invisible chest access'-mode for admins. In case the admins on your server have problems creating player shops and receive the 'You cannot access the selected chest'-message, this might likely be the cause. These 'invisible chest access'-modes usually work by canceling the interaction with the chest and then having the plugin open the chest manually for the player. This feature conflicts with how the Shopkeepers plugin tries to determine if the player can access the selected shop chest. Your admins will have to disable this 'invisible chest access'-mode before they are able to create player shops. For example, the plugin OpenInv offers a silentcontainer and an anycontainer mode, which can be toggled via commands. There are also permission nodes to disable these modes for your admins by default.
• InventoryEdit: This plugin cancels all inventory clicks for inventories with 45 slots, and thereby prevents players from setting up trades inside the shopkeeper editor.
  Edit: The author of this plugin has made changes so that this only applies to inventories that have "&aInventory" in their title. This should resolve the issue in most of the cases. However, since the inventory title is something that could be modified by players or admins (e.g. via configurations, or by renaming the shopkeeper), using the inventory title to identify the inventory is still prone to cause this issues for some custom inventories views.
• uSkyBlock: Some plugins prevent trading with Shopkeepers. If you get a message along the lines of villager-trading is not allowed, check if you are using the uSkyblock plugin. This plugin has the settings villager-trading and villager-trading-enabled (hidden and enabled by default) which also prevent opening the trading inventory for Shopkeepers.
• IllegalStack: The IllegalStack plugin detects and removes the page buttons from the Shopkeeper editor inventory view, because we use writeable-book (book-and-quill) items with the stack size representing the page number, but these writable-book items are usually not stackable in vanilla Minecraft. You could either change these items to something else inside the Shopkeepers config, or see if the IllegalStacks plugin offers a setting to disable this check for the Shopkeepers inventory. However, so far I am not aware of such a setting. I contacted the author of that plugin so that he can hopefully look into detecting and then ignoring Shopkeepers' custom inventories somehow.
• AdvancedSpawners: A user reported an issue with Shopkeeper mobs duplicating and was able to track the issue down to the AdvancedSpawners plugin. Unfortunately the plugin is behind a paywall, so I cannot look into what might be causing this issue or whether there is some kind of setting or workaround to resolve it. According to the user, this has been fixed in a newer version of the plugin, but there is still some issue with the shopkeeper mobs being damageable. Another user reported an issue about "mobs from the plugin being spawned instead of vanilla mobs".
• AdvancedEnchantments: This plugin has a feature to store 'collected souls' inside of items (http://prntscr.com/tqlgbs). Items with different amounts of stored souls won't match and will therefore not be tradable. If this is causing issues for you, check for all souls related config and item settings and disable them (https://image.prntscr.com/image/eBOLjajUTAmvD11rWFLm3g.png, http://prntscr.com/tqsih5)
• MMOItems: A user of this plugin had the following issue on MC 1.16.1. He set up shield items which could be interacted with for a 'charging' effect. After this action has been used once, the internal data of the item had changed from BlockEntityTag: {id:"minecraft:banner", ..} to BlockEntityTag: {id:"banner", ..} (https://prnt.sc/tq7v0w). After this change, the item could no longer be traded in shopkeepers due to this internal difference.
  Also, make sure that you don't configure the plugin to produce items with random values, since these differences will cause these items to not be tradable.
  Someone else had issues with the display name and lore created by the plugin not matching Spigot's internal data format (https://prnt.sc/u1takr ). But according to their feedback they are using the Spigot API to set those item properties. So I can't really explain why their item ended up using an internal data format for those item attributes which differs Spigot's item data format.
• EcoEnchants: This plugin creates custom enchantments, which are not properly supported by Spigot and may therefore occasionally cause issues (eg. when plugins are reloaded, or when the (random) order in which plugins are loaded changes..).
  Additionally, this plugins seems to modify outgoing and incoming item packets for all enchantable items (regardless of whether they actually contain enchantments). In the process of doing that, the plugin also modifies these original items (http://prntscr.com/uait5a), which causes trading to fail, because the actually traded item ends up no longer matching the expected traded item.
  A user reported that after some update which was supposed to fix this, other items besides tools are affected by this as well now.
  Edit: Another user reported having issues with trades with enchanted items (such as regular enchanted books) not working. In combination with the plugin Eco, this plugin seems to modify the data of enchanted items in villager trades (https://github.com/Auxilor/EcoEnchants/blob/master/eco-core/core-plugin/src/main/java/com/willfp/ecoenchants/display/EnchantDisplay.java).
  Edit: The Eco related issues seems to be resolved with Eco 5.3.0 and EcoEnchants 7.2.8.
• Eco: This issue might be related to the EcoEnchant issue above, since Eco is a dependency of EcoEnchants. This plugin seems to modify the ItemStacks of merchants whenever the merchant recipes are sent to a player (and inside of hover events of chat messages, but that is probably a minor issue). The purpose of this might be to modify how certain items are displayed for the player. However, probably due to a missing cloning of the merchant recipes, the ItemStacks seem to not only be modified inside of the outgoing packet, but affect the actual items of the underlying merchant as well. The result is that any items retrieved from a villager (including those of the Shopkeepers plugin) will contain additional data internally, which causes them to not stack with other supposedly equal ItemStacks. In the analyzed case, all result items always end up with at least the additional data tag: {PublicBukkitValues: {"eco:finalized":1}}. Reference: https://github.com/Auxilor/eco/issues/3
  The author changed the plugin so that this only affects items with a max stack size greater than 1, in order to resolve an issue with items not stacking due to this. However, this doesn't actually solve the underlying issue that the plugin is still modifying certain items (eg. tools, weapons, books, .. any item with a max stack size of 1), which breaks any Minecraft mechanic and other plugin that compares items (eg. villager trades with more than 1 input item, shop plugins, plugins that setup crafting recipes that need to exactly match, etc.).
  Edit: The author made another change which might have resolved this Eco-specific issue regarding the finalized property (https://github.com/Auxilor/eco/commit/dbfef3094bc60bb8f605b7c28199c7ae848605b0).
  Edit: A later change (https://github.com/Auxilor/eco/commit/e9e39345edc9157d38fc9c521a868b6aa080ab80) seems to have reverted what I previously assumed might have fixed this issue. A user confirmed still having issues with this when the result item has a max stack size of 1.
  Edit: The author made further changes with Eco 5.3.0 to copy the MerchantRecipes and items before they are modified and then sent to clients. This seems to resolve this incompatibility issue. This update also removes the need for items to be tagged with the finalized data.
  Edit: The author reverted parts of his changes again (https://github.com/Auxilor/eco/commit/d65c04aaa75fe08bdcd116f5f75eb0f7dddbbef1), but then added a config option (disable-display-on-villagers) to disable this (https://github.com/Auxilor/eco/commit/e61e9bc0a8ecdd94635968ecd54b591b593c7737).
  Edit: The author reverted some of his changes to copy the sent MerchantRecipe again but this time also accounts for copying the 'specialPrice' of merchant recipes (https://github.com/Auxilor/eco/commit/07726959e92c92af0da5a99b432a25a5b4d29743).
  Edit (2023-01): I briefly looked into this again and proposed some potential fixes here: https://github.com/Auxilor/eco/issues/227
• EcoItems: Several users have reported issues related to this plugins with trades not working. There already have been compatibility issues with the other Eco plugins in the past (see above). But I don't know whether the EcoItems issue is related to those or caused by something different. However, after having already spent too much time keeping track of the Eco-related compatibility issue mentioned above, I won't spent any further time debugging this or any other Eco-plugin related issues. Your best bet is to inform the Eco plugin developer about the problem so that he can hopefully look into the issue.
• GoldenEnchants: This plugin adds custom enchantments to the server, which is not properly supported by Spigot and may therefore occasionally cause issues. For example, when plugins are reloaded, or when the (random) order in which plugins are loaded changes, shopkeeper trades that use items with these custom enchantments may fail to load, or persistently lose these enchantments.
• CustomItems: A user reported to have trading issues with some items created by this plugin. However, as no NBT data was ever provided for the involved items, I was not able to investigate what kind of item data is causing this issue.
  Another user, who had issues with this plugin as well in the past (about a year earlier), tried to reproduce the issue on 2021-09-25, but was not able to anymore. So maybe this issue is no longer present on the latest versions of Spigot. The user provided the following item NBT data: {id: "minecraft:bread", tag: {display: {Name: '{"extra":[{"bold":false,"italic":false,"underlined":false,"strikethrough":false,"obfuscated":false,"color":"#EAAE69","text":"Cuernito"}],"text":""}', Lore: ['{"extra":[{"bold":false,"italic":true,"underlined":false,"strikethrough":false,"obfuscated":false,"color":"#714AB2","text":"\\"Ulala, un Croissant!\\""}],"text":""}']}, CustomModelData: 3, com.jojodmo.customitems.itemID: "cuernito", com.jojodmo.customitems.itemVersion: 1, com.jojodmo.customitems.internalVersion: "1"}, Count: 64b}
• MythicMobs: Items created by MythicMobs use legacy color codes within modern text components (eg. http://prntscr.com/we8kcs , serialized: http://prntscr.com/we8l0n). Side note: Both Spigot and Minecraft recommend to not mix these (see Spigot wiki and the various Mojang tickets involving the no longer supported use of legacy color codes). On the latest versions of Spigot (late 1.16.4), Spigot will now properly persist this text representation when the item in saved and reloaded by plugins (such as Shopkeepers).
  However, previously saved items (eg. in previously setup shopkeeper trades) have been saved as plain (legacy) text. When Spigot loads these items, it converts the legacy text to a specific text component representation. This representation does not match what MythicMobs creates for new items, so newly created items won't match items that have been saved on previous versions of Spigot and can't be used in trades involving those previously created items. The only solution is to freshly setup any trades involving these items.
  Note: I was only able to reproduce this issue on Paper. On Spigot the items seem to not contain legacy color codes (maybe due to some automatic conversion/validation done by Spigot).
  Edit: Another related issue with these invalid MythicMob items and Paper is that Paper includes a patch that automatically converts these items on later occasions (such as when a player rejoins the server). It is therefore possible for players to end up with two incompatible (non-matching) variants of the same item. Shopkeeper trades that use one of these item variants won't work with items of the other variant. See also https://github.com/PaperMC/Paper/issues/4888
  Edit: According to user feedback, the latest version of MythicMobs (currently 4.13.0) seems to no longer generate items with legacy color codes. However, your players and previously setup shopkeepers might still use the old item variants, and the new and old items might not be compatible with each other. There is no solution yet to automatically convert these different item variants on the server (in player inventories, in containers such as chests, dropped items, etc., and in shopkeeper trades) to one common (eg. the latest) variant. Some MythicMobs version also added a new MYTHIC_TYPE tag to generated items, which yields another item variant that might cause stacking or comparison issues with previously created items on your server.
  2024-04-27: Some users ran into the issue of Shopkeeper villagers turning into normal villagers that is apparently caused by the "Vanilla Overrides" feature of MthicMobs.
• Fabric/Lithium/Cardboard: A user encountered a 'class not found' exception for a class named 'net/minecraft/class_1352' when Shopkeepers initializes. He mentioned that he had been running Fabric and Lithium earlier and then reverted to a regular Paper server. The issue was that something modified the Shopkeepers plugin jar and remapped all nms classes to how they are named in Fabric. I can't tell for sure what caused this remapping, but it seems like Cardboard (a Bukkit-to-Fabric mod) is doing exactly that. So maybe the user has been using that in the past, then reverted to a regular Paper server, and ran into the issue that the previously remapped Shopkeepers plugin jar nor longer worked.
  Another user reported that the plugin loads fine on Fabric with Cardboard, but they were not able to open the shopkeeper editor by right clicking.
• NoMobLag: This plugin's 'mob freezing' and NoAI features seem to conflict with other plugins that intentionally disable the AI of specific mobs with the NoAI flag (such as for example the Shopkeepers plugin, which spawns mobs with the NoAI flag in order to make them stationary). According to a user's report, this plugin seems to forcefully enable the AI again for these mobs, causing them to wander around even though they should remain in this NoAI state.
  Previously, disabling mob-freezing.enable-freezing and mob-freezing.enable-ai-on-chunk-load would resolve this incompatibility, but also disabled this feature completely.
  I informed the plugin author about possible solutions (https://www.spigotmc.org/threads/%E2%9D%8C%E2%98%A2%EF%B8%8F-nomoblag-%E2%98%A2%EF%B8%8F%E2%9D%8C-entity-farm-limiter-spawner-nerf-mob-freezing-more.404659/page-2#post-4060641).
  The author then added the setting no-ai-tags with a default entry for the shopkeeper tag, so that shopkeeper mobs could be ignored. However, they also added the behavior to forcefully enable the AI of all mobs again (regardless of the configured no-ai-tags) whenever a player walks into a chunk IF you disabled mob-freezing.enable-freezing. So to prevent this from causing the shopkeeper mobs to start walking around again on the latest versions (checked v2.3.3), you actually need to enable the mob-freezing.enable-freezing setting and ensure that the no-ai-tags contains an entry shopkeeper. I informed the author of this (https://www.spigotmc.org/threads/%E2%9D%8C%E2%98%A2%EF%B8%8F-nomoblag-%E2%98%A2%EF%B8%8F%E2%9D%8C-entity-farm-limiter-spawner-nerf-mob-freezing-more.404659/page-3#post-4237068).
• MC-164353: This affects the villager editor for regular villagers. Due to a Minecraft bug, villagers without profession will instantly close their trading GUI currently (tested on MC 1.16.5).
• JobsReborn: This plugin adds the NBT data JobsItemBoost: <item-name> to every item it creates. The purpose of this seems to be to more easily find the item configuration that is associated with a specific item. If you are using the Shopkeeper setting use-strict-item-comparison, this difference in internal item data will cause any trades to fail that require an item without that additional data.
• Shulker boxes: Shulker boxes have different internal data if they have been placed and picked up at least once. A newly created shulker box item has no internal data. After placing it and picking it up again, it will have the additional data BlockEntityTag: {Items: []} which usually contains the data for the stored items, but can also be empty if the shulker box contains no items. If the trade requires a shulker box with this additional data, it won't accept a newly created shulker box item (since it misses that data). And if you have the setting use-strict-item-comparison enabled, the same applies in the opposite direction as well: If the trade requires a shulker box without this data, it won't accept a shulker box that has this data (i.e. that has been placed and picked up before).
  A similar issue affects shulker box items that were created in earlier MC versions: When a shulker box block is saved, its data contains a property id: "minecraft:shulker_box" which identifies the type of the stored block entity. In earlier MC versions, shulker box items also stored this id property inside of their BlockEntityTag. And this id property is also updated and kept during Minecraft's item data migrations. However, on current MC versions (tested on MC 1.16.5) the loot table logic that controls how the shulker box item is created when a shulker box block is broken only takes into account the items contained by the shulker box and transfers only those to the BlockEntityTag of the dropped item. Consequently, the shulker box item dropped by breaking a shulker box block does not contain this id property, and will therefore not match any older shulker box items that still contain this id property. Any shopkeeper trades that require a shulker box with this id property will therefore not accept any shulker boxes that do not contain this id property. And if a player places a shulker box item that still contains this id property, and then picks up the block again by breaking it, the resulting shulker box item will have lost its id property in the process.
• BungeeCoord chat plugins: The shopkeeper naming feature relies on the Shopkeepers plugin being able to detect when players write a chat message (i.e. detect chat events). On a regular Spigot server, this is always possible. But if the server is behind a BungeeCoord (or other kind of) proxy, plugins or features on that proxy-level can prevent chat packets from the players to reach the underlying Spigot server. For instance, a chat muting plugin may cancel the chat packet on the proxy level, or a proxy-level chat plugin may implement its chat functionality by cancelling the chat packet and then manually sending the chat messages to all receiving players.
  I created a BungeeCoord and Spigot plugin that forwards cancelled chat events from the BungeeCoord proxy to the player's Spigot server ( https://www.spigotmc.org/resources/bungeeforwardcancelledchat.88941/): If you are affected by this issue, installing this plugin (on both BungeeCoord and the Spigot servers) might resolve the issue.
• InvSee: This plugin forcefully uncancels inventory click events for all inventories when the player is not using the invsee feature currently (ref: https://image.prntscr.com/image/Sak5a0E4SC6-QHfNu3Lljw.png). One effect of this is that players are able to pick up the items from within the shopkeeper editor inventory. I reported this to the author here: https://www.spigotmc.org/threads/invsee-plugin-with-config-1-8-x-1-16-5.412888/#post-4093874
• AutoSort: This plugin sorts chest-typed inventories, without differentiating between regular chest inventories and custom inventories created by other plugins. This breaks, for example, the editor of the Shopkeepers plugin. Ticket: https://github.com/DougKeller/AutoSort/issues/2
• WildStacker: Some user reported that this plugin might be incompatible with Shopkeepers. I haven't looked into this plugin in detail and have no information yet on what exactly the issue might be, and whether it has to do with the plugin's item stacking logic. However, most of their inventory click event listeners ignore cancelled click events, and the Shopkeepers plugin should be cancelling most of its click events early. However, I noticed that they use a custom 'glow' enchantment: The Shopkeepers plugin does not properly support custom enchantments, so any items that use this custom glow enchantment might no longer work in trades after reloads of the Shopkeepers plugin.
• Issues with the plugin attempting to load javassist classes: Some users have reported that they are getting errors about the Shopkeepers plugin not able to find or load javassist classes (https://discord.com/channels/606329645779910686/606332085308751892/816261390708244511 , https://discord.com/channels/606329645779910686/606332085308751892/877061080667553832). However, the Shopkeepers does not use the javassist library, so I cannot explain currently what is causing this error. Since javassist is a library for dynamic manipulation of bytecode, my guess would be that maybe some other plugin, or a custom server implementation, or maybe even the server hoster, is modifying the Shopkeepers plugin jar at runtime. One user posted his list of plugins (https://pastebin.com/0v26ffRm). If you are also having this issue, check if you have any plugins in common, and then check if any of these plugins make use of the javassist library, or any other bytecode manipulation library that might internally use javassist, such as ASM.
• Knokko's Custom Items: This plugin periodically scans all player inventories and the equipment of all entities on the server to check if it should 'update' some of those items. In either case, the plugin seems to set a LastExportTime timestamp on its custom items as a sort of optimization for this item checking. Two items having different internal timestamps of this LastExportTime won't be considered equal by Minecraft or Shopkeepers, causing issues like items not stacking in certain situations, or items not being accepted by Shopkeeper trades. Relevant ticket: https://github.com/knokko/custom-items-gradle/issues/138
• Tracking Compass: This plugin (I checked version 5.4) forcefully uncancels inventory clicks for inventory views whose titles do not match any of the plugin's expected inventory view titles. This allows players to pick up items in custom inventory views, or perform other inventory actions such as trading/crafting/etc. that are supposed to be cancelled. This can also result in item duplication bugs.
  Additionally, the plugin identifies its custom inventory views by title. This is probably not safe. For instance, the Shopkeepers plugin allows players to rename their shopkeeper NPC, and then open an inventory menu to edit it. This editor menu will use whatever name the player set for their NPC. So players could potentially name it just like one of the custom inventory view titles of the TrackingCompass plugin and thereby cause the TrackingCompass plugin to process inventory clicks inside of it even though it is not supposed to do that. A better alternative could be for the TrackingCompass plugin to keep track of each custom inventory it opens for a player, check during the InventoryClickEvent handling if the inventory matches the custom inventory it is tracking for the player, and stop the tracking again when it receives an InventoryCloseEvent.
• Citizens: If you get errors like "IllegalStateException: no implementation set", you need to do two things to resolve the issue:
  • Update your Citizens plugin. To workaround some changes in how Spigot unloads plugin classes, Citizens decided to shut itself down whenever a plugin with a Citizens (soft-)dependency disables itself. This also disables the CitizensAPI, which results in these errors inside the log: The Shopkeepers plugin tries to invoke some CitizensAPI operation after the CitizensAPI has been disabled.
    On newer Citizens versions, they partially reverted some of these changes: Instead of fully disabling the CitizensAPI in this case, they 'only' trigger a save of all NPCs and then disable all further saving of NPCs. Since the CitizensAPI remains enabled, this should resolve this error. But you might still run into issues with some subsequent changes to NPCs not getting saved to disk.
  • Make sure that no plugin with a (soft-)dependency on Citizens is dynamically disabled, outside of server shutdowns. This avoids triggering this partial Citizens shutdown, and thereby also avoids issues with NPCs not getting properly saved to disk.
• DiscordSRV: This plugin is considerably messing with Bukkit's underlying event system implementation. This goes so far that they are even replacing Bukkit's underlying data structures with their own, or wrapping all event handlers registered by plugins with their own implementations. One issue that has been caused by this in the past is https://github.com/DiscordSRV/DiscordSRV/issues/1347.
  The last time I checked (2021.12.26), the primary goals of these changes seem to be reacting to all events universally, and detecting which plugin has cancelled a particular event. However, so far, most of these operations are only used when certain debug features are enabled.
  This particular issue was resolved in a later version of DiscordSRV. However, if you use this plugin and you run into any issues, especially involving events, event ordering, event un/registration, etc., then first try to reproduce your issue without this plugin running, and also with all of its debugging features disabled (Debug, DebugLevel, etc.).
• Mohist: Running Shopkeepers on a Mohist server is not officially supported. I won't spend the time and effort to investigate issues that cannot be reproduced on a normal Spigot server. Your best bet is therefore to contact the Mohist developers to look into any discrepancies between Mohist and Spigot that could affect plugins such as Shopkeepers. That being said, there are a few known issues when running Shopkeepers on Mohist:
  • Issue #738: Mohist reports the wrong inventory type for merchant inventories, which breaks some internal checks of the Shopkeepers plugin, which, as a safeguard, causes the trading inventory to be immediately closed again when someone tries to interact with it. On newer versions of Shopkeepers, this safeguard can be disabled with the setting disable-inventory-verification. This setting is also automatically enabled when the plugin detects to run on a Mohist server.
  • On newer versions of Shopkeepers, the plugin performs some basic checks during startup to verify that certain aspects of the server implementation work as expected. One of the tested aspects is that the comparison of item stacks works correctly (which is quite essential for an item-based trading plugin).
    A user has reported that one of these checks (comparing a Bukkit ItemStack with a corresponding CraftItemStack) fails, and that the plugin therefore disables itself to avoid subsequent problems. I have not yet looked into this further, i.e. I don't know what is causing this issue, or if this issue only affects specific kinds of items. But ideally, this is something that should be reported to the Mohist developers so that they can further debug this. If you want to take the risk and trying running the plugin anyway, you can enable the setting ignore-failed-server-assumption-tests.
• Magma: The same notes and issues as with Mohist also apply to Magma. If you are having issues with the trading UI closing, try setting disable-inventory-verification to true inside the Shopkeepers config. If you run into any other problems, you will have to contact the Magma developers about it so that they can look into it if they are interested in resolving the issue.
• NoVillagerTrade: This plugin prevents access to the villager trading menu, and intentionally also prevents accessing the trading menu of shopkeepers. If you instead only want to prevent access to non-shopkeeper villagers: The shopkeepers plugin has a setting for that disable-other-villagers.
• ToolStats: This plugin modifies the internal data of held items on various circumstances (block broken, mob/player killed, etc.) in order to track certain item usage statistics. Consequently, if you set up a shopkeeper trade that requires one of these items, players will only be able to use the trade if they offer an item with exactly the same tracked statistics and internal item data.
  Additionally, a user (using Paper as their server) reported that this plugin somehow caused trades to fail with a "Trade aborted: The traded items do not match what this shopkeeper expected." error, even when the tool item was being sold instead of being bought. However, this error message is usually only expected to occur when some other plugin modifies the trade result item during the trading.
  I have not yet tried to reproduce this issue myself, but one guess is that this issue might be Paper-specific, caused by the fact that the ToolStats plugin modifies the lore of items in a way that the item lore can end up with json text components mixed with legacy color codes. Paper contains a change to automatically convert items that contain lore with legacy color codes. This can explain why the trade appears to work at first (shows the result item), but is then aborted by the Shopkeepers plugin because it cannot find the trade offer that matches the trade's result item: The trade result item inside the trading GUI went through this Paper item conversion, whereas the trade offer stored by the shopkeeper might not necessarily have been converted yet (e.g. if the trade was freshly set up and the Shopkeepers plugin has not yet been reloaded since then).
• AttributeHider: In some cases, this plugin might modify the items inside your inventory and inside the villager trading GUI. This can result in trading issues due to the item offered by the player not matching the item required by the shopkeeper, or due to the result item inside the trading UI being modified and then no longer match the expected result item of the corresponding shopkeeper trade offer.
  According to the plugin's changelog, the plugin was refactored in the past with the goal to only modify the items visually by editing outgoing packets. However, this does not seem to actually be the case. Relevant ticket: https://github.com/Warren1001/attributehider/issues/7
  Edit: The author has made changes that should hopefully fix this issue. However, I did not test the fix myself yet. Also, if you have been using this plugin before, you may still have some items on your server that have previously been modified.
• NoCheatPlus (and other anti-cheat plugins): In order to verify that a player can access the chest when they create a new player shopkeeper, the Shopkeepers plugin triggers a dummy interaction with the chest block (PlayerInteractEvent) and checks if any of the other plugins cancel this interaction attempt. However, anti-cheat plugins, like for example NoCheatPlus, likely have checks to detect and prevent players from interacting with blocks that are out of range or out of sight. So players might run into issues when they try to create player shops further away of the shop chest.
  Currently, there is no workaround yet for the Shopkeepers plugin to bypass these anti-cheat plugin checks. Right now, the only option is to disable the corresponding anti-cheat checks.
  In the case of NoCheatPlus, there are config settings (direction, reach, and visible under the blockinteract category) that can be disabled, and there are permission nodes for players to bypass these checks (nocheatplus.checks.blockinteract.reach, nocheatplus.checks.blockinteract.direction, nocheatplus.checks.blockinteract.visible).
  One idea to resolve this incompatibility, without having to hook into the API of all the various anti-cheat plugins out there, is to add a new setting to the Shopkeepers plugin that allows admins to define a list of bypass permission nodes that are temporarily assigned to the player during the interaction check (https://github.com/Shopkeepers/Shopkeepers/issues/786). But this feature has so far not yet been added.
• ItemEffects: Some users reported an issue with players apparently being killed several times in a row, lagging the server, and somehow duplicating their held or traded items, when being killed while trading with a shopkeeper. They tracked the issue down to this plugin. No further information is available regarding the underlying cause of the issue, or whether it only affects specific shopkeepers, or when specific items are involved. It is also unclear if this plugin alone is somehow causing the issue, or if the issue is caused by a combination of multiple plugins.
  While checking the plugin, I noticed a few other potential issues: The plugin reacts to interactions with certain named inventories. For example, if an inventory with any of the following names is closed (Item-Effecter, Stored Armors, Choose Effects, Choose Armor type, Item-Effecter-Armor), the plugin will drop the items of the inventory. And the plugin might be able to apply potion effects to players if their items contain certain words in their lore (possibly including effects such as instant_damage). And it might be possible for the plugin to restore a player's health to that of one tick early in certain cases, maybe even reviving the player by that. However, these potential issues have not been confirmed, and it is still unclear if or how they might be related to the reported item duplication issue mentioned above.
• ViaVersion: Several users ran into issues with clients being disconnected whenever they opened the trading menu of some shopkeepers with certain trades (errors: different variations of something along the lines of "DecoderException"). Some users reported that the issue only affected trades with specific custom items. Other users were able to reproduce their issue with regular items without any NBT data. In some cases, this issue only affected trades that require 2 items. In some cases, the users reported that updating to a later snapshot build of ViaVersion apparently resolved the issue.
• Protocolize: A user ran into an issue with trades sometimes not working (2022-6-28): The client was displaying the result item of the trade, but the server and the Shopkeepers plugin reported this slot to be empty. Apparently, the issue was somehow caused by this plugin (or another plugin depending on it) on the proxy server.
• CustomEnchantments: This plugin contains a feature that will perioidcally and whenever a player opens an inventory scan the inventory and delete certain 'duplicate' items. This feature seems to primarily affect enchanted tools with matching data. The plugin will then print a red message along the lines of "Removed duplicate items". This feature is enabled by default, but can be disabled via the AntiDupe setting inside the config.
  This feature will also delete duplicate items from the shopkeeper inventories, such as the shopkeeper editor view. So when this feature is active, you will run into issues when you try to set up multiple trades for the same item. Or when players try to buy some item multiple times.
• CMI: A user reported that when this plugin runs besides Shopkeepers, the Shopkeepers plugin would not start due to one of its "server assumption tests" failing with an error along the lines of "Cannot invoke 'org.bukkit.enchantments.EnchantmentWrapper.getEnchantments()'" and "'org.bukkit.enchantments.EnchantmentWrapper.getEnchantments()' is null". They are using a Paper 1.19.4 server. No further information is available, other than that removing CMI has resolved the issue. Maybe CMI is messing with Bukkit's default enchantments in some way. But without access to the plugin or insight into its source code, the issue or its cause cannot be confirmed or further investigated.
• PlugMan: Reloading the Citizens plugin via PlugMan seems to leave the Citizens API in an unusable state (the API implementation remains unset). I haven't verified this yet, but one guess is that this is maybe caused by the reloaded plugin loading a new copy of its classes inside a new class loader: I.e., a second CitizensAPI class is initialized, but other plugins like Shopkeepers still reference the original one. If that is the case, I don't think there is a way to resolve this in neither the Shopkeepers nor the Citizens plugin. You will have to avoid reloading individual plugins via PlugMan.
  The same kind of issue might also apply when reloading other dependencies of the Shopkeepers plugin.
• ShopkeepersAddon: A user reported that their server crashes whenever they reload the Shopkeepers plugin due to the reload taking longer than 10 seconds. They have around ~550 shopkeepers. It turned out that the ShopkeepersAddon plugin is doing a lot of processing whenever a shopkeeper is unloaded (GuiListeners.onShopkeeperDelete). Removing this addon plugin resolved the issue and the reloading then only takes "a few seconds".
• ItemsAdder: In the past, some users have reported issues related to using ItemsAdder items in shopkeeper trades. It is not completely clear what is causing those issues and whether it only affects certain items. Also, a user reported that ItemsAdder items with an emote in their description resulted in the item becoming invisible in the trade result slot.
  Another user provided an example of an item created by ItemsAdder containing legacy color codes in their text data: The server (especially Paper) can end up converting such text data to a different internal representation in various circumstances, including when the Shopkeepers plugin stores such items, resulting in the converted items no longer matching the original items.
• ExecutableItems: A user noticed that non-admin users were not able to trade. It turned out that they were using items created by the ExecutableItems plugin and the items were configured to cancel-merchant trades. See https://docs.ssomar.com/executableitems/configurations/item-configuration/item-restrictions-resistances.
• SuperiorSkyblock2: A user reported an issue with the shopkeeper trading UI that turned out to be caused by this plugin. With debug mode enabled, the Shopkeepers plugin logged something along the lines of "Ignoring late inventory event (InventoryClickEvent): UI session 'trading' of player X is no longer valid. Some plugin might have unexpectedly closed the inventory while the event was still being processed!". They apparently fixed this issue by setting protection: false in the SuperiorSkyblock2 configuration. *Honey-AntiCrash: A user reported that they are getting kicked when this plugin is running and they try to use the buttons inside the shopkeeper editor to swap pages. No further information was provided.

If you run into issues with clients being disconnected or trading not working correctly, try to reproduce your issue without any packet modifying plugins such as ViaVersion, ProtocolLib and plugins that depend on it, Protocolize, etc.

Previous Minecraft and Shopkeepers versions:

• MC 1.20.5/1.21:
  • With Minecraft's change to item data components, the validation of item data has become more strict and Minecraft might silently drop item data that it no longer considers valid. For example, if you previously used enchantments with an invalid level such as 0 to make items glow, these enchantments will silently get deleted from all items on the server when you update to MC 1.20.5+. This not only affects items in shopkeepers, but all items on the server. Unfortunately, I am not aware of any solution that would enable you to specify custom item data migrations that apply to all items on the server. If there exists such a general-purpose solution, let me know!
  • Spigot 1.20.5/6 includes some item-related bugs that break the Shopkeepers plugin if you use any of the affected items, such as SPIGOT-7789 (firework items), SPGIOT-7804 (written book items), SPIGOT-7671 (items with invalid flags). Some of those issues have been fixed, but only in later Spigot 1.21 versions.
• GriefPrevention: In order to prevent other plugins from handling interactions with Shopkeeper mobs (including preventing protection plugins from printing their 'You cannot interact with that entity' messages) the Shopkeepers plugin reacts to entity interactions as early as possible and cancels the interaction event so that other plugins can ignore it. This works fine for most plugins (like for example WorldGuard). However, GriefPrevention handles entity interactions very early as well. In that case the order in which those two plugins handle the entity interaction event is determined by their startup order. Shopkeepers has a 'loadbefore' entry inside its internal plugin.yml configuration in order to get loaded before GriefPrevention when you freshly start the server. However, this order breaks whenever you manually reload the Shopkeepers plugin without also reloading the GriefPrevention plugin afterwards. The GriefPrevention developer has promised to consider changing their event handling priority in GP v20 (reference). There is also some related discussion in a GP PR.
  A workaround has been added in Shopkeepers v2.13.0 that should resolve this issue.
• MC 1.18.2: Early builds of Spigot 1.18.2 had some chunk loading related issue (https://hub.spigotmc.org/jira/browse/SPIGOT-6980) that might affect the activation (spawning, ticking, etc.) of shopkeepers. This has been fixed in later builds, so make sure that your server is up-to-date.
• ChatColor: When naming a shopkeeper, the Shopkeepers plugin uses the player's next chat input to set the new shopkeeper name. By default, color codes are not allowed to be used in shopkeeper names (but you can enable them inside the config via the name-regex setting). However, this ChatColor plugin seems to inject (at lowest event priority, i.e. very early of the chat processing) a chat color at the beginning of every message sent by players. Depending on the random order in which the Shopkeepers plugin extracts the chat message to apply it as new shopkeeper name, and the ChatColor plugin modifying the chat message to inject this color code, the Shopkeepers plugin might complain about the chat message not being a valid shopkeeper name, due this this additional color code at the beginning.
  To resolve this plugin incompatibility, you previously had to either remove the ChatColor plugin, or enable color codes for shopkeeper names inside the Shopkeepers config. I left the plugin author a message about this incompatibility: https://dev.bukkit.org/projects/chatcolor-s#c371
  Edit: Newer versions of the ChatColor plugin now contain a setting to manually change the event priority at which the ChatColor plugin modifies the chat message. However, this is likely only useful once you have identified the casue of the Shopkeeper naming problem.
  Newer versions of the Shopkeepers plugin contain a workaround to resolve this issue by default: The Shopkeepers plugin reorders the registered chat event listeners to ensure that it always reads the chat message first, before any other plugins had a chance to apply their chat modifications.
• MC 1.16.3: Some user had an issue with Shopkeepers' regular villager editor (v2.12.0) not opening the editor UI after the villager had already been edited once. Instead, it would always open the trading GUI. I did not reproduce the issue myself, and I also don't know if earlier Minecraft versions are affected as well. However, after updating to 1.16.5, the issue was resolved. The issue affected both Spigot and Paper.
• MC-121932: There was a Minecraft bug which caused the wrong items to be removed for certain trades (when both required items are of the same type but have differing nbt data, and the items are provided in reverse order by the player). However, this only affected older versions of Shopkeepers, before we fully reimplemented the shopkeeper trading. We had to explicitly check for this condition there and then cancel the respective trade attempt. This was fixed in MC 1.16.
• MC-141494: Due to a Minecraft bug interacting with a villager while holding a written book in the main or off hand results in weird glitches and tricks the plugin into thinking that the editor or trading UI got opened even though the book got opened instead. We therefore ignore any interactions with shopkeeper mobs for now when the interacting player is holding a written book.
  This has been fixed in MC 1.16, and we therefore removed this restriction in newer Shopkeepers versions again.
• MC-129515: In past Minecraft versions, double clicking an item in the inventory could trigger a trade but omit excess items, i.e. the trading player would not receive all of the trade result items. In our shopkeeper trading implementation, we therefore ignore and cancel this inventory action if the clicked item matches the trade result item. Since MC 1.14, Mojang has also fixed this by fully disabling the ability for players to collect items to their cursor by double clicking them when inside the trading UI (https://bugs.mojang.com/browse/MC-148867). Our own check to cancel this inventory action still exists, just in case, but it should no longer be possible to trigger it in vanilla Minecraft.
• Cubedcraft: A user was using v2.2.4 of Shopkeepers on a 1.8.8 server of Cubedcraft. The trades were not showing up inside the trading menu. I was not able to track down the issue. On a regular Spigot server running the same server and plugin versions, the plugin worked fine. Also, the installed plugins did not provide any indication in regards to the cause of the issue.
• If you are running on a Minecraft version below MC 1.11, you can no longer cycle through the different zombie variants and skeleton variants. Existing shopkeepers using those will fallback to normal zombies and skeletons.
• Shopkeepers using skeleton or zombie variants after updating to MC 1.11 or above can not be loaded again (will be lost) when switching back to a previous Minecraft version.
• On MC 1.9 and MC 1.10 any spawn egg type is accepted as shop creation item. If you are updating, you may have to change the data value to '0' in the config for spawn eggs to work at all. For 1.11 and later there is a new config setting to specifiy the spawn egg mob type (see changelog of v1.83).
• In the latest MC 1.8.x versions, Minecraft's trading logic has slightly changed (and by that the one of Shopkeepers as well): If a trade requires an item with special data (like a custom name, lore, enchantments, etc.), Minecraft is now only allowing this trade if the offered item contains all of this data as well. The offered item may however contain additional data.
• The always-show-nameplates setting is not working on MC 1.8. On later versions it works again.
• On early versions of Shopkeepers, server crashes and improper shutdowns might cause living non-citizens shopkeeper entities to duplicate sometimes.