Common Issues - READ BEFORE POSTING

[mdcfe]

This pinned thread aims to cover common issues people encounter with EssentialsX.

Users: Before creating a new issue, we encourage you to search (Ctrl-F) this thread to see if there is a suggested solution or workaround to your issue before you open a new issue. If you don't see your issue listed here, you can also use the search bar and filters on the main issues list:

Only EssentialsX team members can add to this list. If you spot a problem that should be covered here, you can recommend an issue by replying to #3955.

---

Maintainers: When adding an issue here, you should post one issue per comment, using the following format:

## Problem: Players can't build or interact with anything

**Details:** After installing EssentialsX, players are unable to place, break or interact with blocks in the world unless they are opped.

**Cause:** You probably installed installed EssentialsX AntiBuild by mistake.
AntiBuild restricts building using permissions on your server, but if you want all players to be able to build, you probably don't want to use AntiBuild.

**Solution:** Delete the `EssentialsXAntiBuild-<version>.jar` file from your server's `plugins/` folder.
(You might also want to check whether you need the other optional modules - see the [Module Breakdown wiki page](https://essentialsx.net/wiki/Module-Breakdown.html).)

[mdcfe]

Problem: Players can't build or interact with anything

Details: After installing EssentialsX, players are unable to place, break or interact with blocks in the world unless they are opped.

Cause: You probably installed installed EssentialsX AntiBuild by mistake.
AntiBuild restricts building using permissions on your server, but if you want all players to be able to build, you probably don't want to use AntiBuild.

Solution: Delete the EssentialsXAntiBuild-<version>.jar file from your server's plugins/ folder.
(You might also want to check whether you need the other optional modules - see the Module Breakdown wiki page.)

[mdcfe]

Problem: /invsee randomly swaps items around

Details: When using /invsee to modify a player's inventory, items are randomly swapped and moved around.

Cause: EssentialsX uses the Bukkit API to open players' inventories. However, as newer versions of Minecraft have been released, this method can sometimes cause issues.

Solution: Don't give staff the essentials.invsee.modify permission. This will let staff view player inventories without modifying them and causing item swaps. If you want to edit player inventories, we recommend OpenInv.

[mdcfe]

Problem: EssentialsX overrides commands from vanilla/Spigot/other plugins

Details: After installing EssentialsX, commands like /give and /help are overridden by EssentialsX alternatives.

Cause: EssentialsX provides enhanced alternatives to several default commands. For example, EssentialsX's /give supports a user-friendly item meta syntax that's less awkward to use than vanilla NBT, while EssentialsX's /help allows server owners to create custom help command pages and even customise them per-group.

Solution: See the commands list for documentation on how to use EssentialsX's commands.

If you're sure you want to override commands, you can use Bukkit's commands.yml. The example below does the following:

• Overrides /gc with spark's /profiler command
• Overrides /tell with the vanilla /tell command
• Forces /msg to run EssentialsX's /msg command

aliases:
    gc:
    - "spark:profiler $1-"
    tell:
    - "minecraft:tell $1-"
    msg:
    - "essentials:msg $1-"

[mdcfe]

Problem: Other plugins' commands are overriding EssentialsX's commands

Details: After installing EssentialsX with other plugins, EssentialsX's commands get overridden by commands from other plugins.

Cause: By default, EssentialsX assumes other plugins' commands should take priority and tries to hand command execution over to other plugins.

Solution: You can tell EssentialsX to try and take priority over other plugins using the overridden-commands section in EssentialsX's config.yml.

For example, to force EssentialsX to handle the /msg command instead of passing it over to another plugin, your section should look like this:

overridden-commands:
  - msg

If this doesn't work, you may need to also set an alias in Bukkit's commands.yml - see this solution for an example.

[triagonal]

Problem: /hat always displays "You must have something to wear in your hand"

Details: Attempting to use /hat always results in the error message "You must have something to wear in your hand", no matter which item the player is holding.

Cause: The player is likely an OP, or inherits the essentials.hat.prevent-type.* as a result of wildcard (*, essentials.*) permissions. The essentials.hat.prevent-type.{item} permission prevents an item from being used as a hat.

Solution: Negate (set to false) the essentials.hat.prevent-type.* permission in your permissions plugin.
In addition, consider not using OP and/or wildcard permissions on your server, and instead use the permissions list to grant players only the permissions they need.

[mdcfe]

Problem: EssentialsX is flooding my console with UUID errors!

Details: EssentialsX shows errors in the console with UUIDs, either on startup, when players log in or when running certain commands.

Cause: We're currently investigating userdata corruption caused by poorly-written third party plugins and server implementations. In order to aid the detection and resolution of these issues, the latest EssentialsX dev builds report signs of userdata corruption in the console, along with a stack trace that indicates possible sources of issues. These warning messages are not harmful on their own.

Solution:

• We have fixed this problem and a solution (Rewrite User storage and UUID cache #4581) will be added in 2.20.0. In the meantime, please ask for help in Discord for instructions for using these builds.

- PlaceholderAPI is known to trigger these warnings. If you use PAPI, keep an eye out for updates to both EssentialsX and the PAPI Vault and Essentials expansions.
- If you're running a Mojang-authenticated (online mode) server, your usermap may have been poisoned with v3 player UUIDs. To fix this, you should:
- Shut down your server.
- Back up and then delete usermap.csv,
- Look for v3 UUID files (in the format xxxxxxxx-xxxx-3xxx-xxxx-xxxxxxxxxxxx.yml) inside your plugins/Essentials/userdata/ folder.
- If any of these files include a npc: true line but are assigned to a real player's name, then they're corrupted player files. Back up and then delete these files.
~~ - Start your server again.~~
- If after all these steps you still face issues, open a bug report. We'll then be able to investigate what the cause of the issue is and help resolve the issue.