Troubleshooting & FAQ
Startup problems
The plugin disables itself on start
Check the console for one of these:
| Log message | Cause | Fix |
|---|---|---|
server-id must be set in config.yml | server-id is blank. This is expected on the very first start. | Set server-id to the name Velocity knows this server by, then restart. |
Could not open the cosmetics database; disabling | EdenEffects could not connect to MySQL. | Check database.host, port, name, user, and password, and that this backend can reach the database. |
Schema migration failed; disabling | The tables could not be created or updated. | Make sure the database user has permission to create and alter tables in the database. |
The server hangs for a few seconds on start
Opening the connection pool waits for the database. If MySQL is slow or unreachable, the server waits up to database.connection-timeout-ms (default 5 seconds) before giving up. Fix the connection, or lower the timeout so a failure is quick.
LuckPerms is not installed; temporary cosmetic unlocks will not work
Permanent permission nodes still work with any permissions plugin. Only temporary unlocks granted through StoneLib need LuckPerms. See Permissions.
Paper's Dialog API is missing on this build; pet editing is disabled
The Paper build is too old for native dialogs. Pets still work, but the pet editor and the "Save current look" dialog are unavailable. Players can still save presets with /cosmetics preset save <name>. Update Paper to fix it.
Sync problems
Changes don't reach other servers
Work through these in order:
- Is the Velocity jar installed? The proxy log should show
Eden Effects relay listening on edeneffects:sync. - Is every
server-idunique, and does each matchvelocity.toml? Two backends with the same ID will skip each other's messages. - Do all backends use the same database? Compare the
databaseblock on each. - Is anyone online on the other server? Plugin messages need a player connection to arrive. A server with nobody on it misses the message, but anyone joining it later loads the latest data from MySQL anyway, so this is not a real problem.
A player's cosmetics are gone after switching server
- The type may be switched off on that server or in that world. The category shows Unavailable on this server in the menu. The selection is kept and comes back elsewhere.
- The player may be vanished or in spectator mode.
- The player may not hold the node on that server. If permissions differ per server (LuckPerms
servercontexts), a cosmetic can be allowed on one backend and not another.
Player-facing problems
"You don't have that one yet."
The player does not have edeneffects.<type>.<id> for that cosmetic. Remember that node prefixes are singular except wings: edeneffects.trail.flame, not edeneffects.trails.flame, and edeneffects.join.arrival, not edeneffects.joins.arrival. See Permissions.
Nobody gets a join or death effect any more
Join and death effects used to be automatic, set by effects.join and effects.death. They are now cosmetics each player chooses, so those keys do nothing. Grant the edeneffects.join.*, edeneffects.leave.*, and edeneffects.death.* nodes and have players pick one from the menu. See Configuration.
A join, leave, or death effect isn't playing
- The player has not chosen one. Nothing plays by default.
- The type is disabled on this server or in that world (
cosmetics.joins,cosmetics.leaves,cosmetics.deaths). - The player is vanished or in spectator mode, where no effect plays.
- The player has lost the node for the effect they chose.
- For a join effect only: it plays a second after joining, so a player who leaves immediately never sees it.
A cosmetic applied but doesn't show
- The cosmetic type is disabled in this world. Check
cosmetics.<type>.enabledanddisabled-worlds. - Trails only draw while the player is moving.
- Other players further than
render.distance(default 48 blocks) do not see trails, hats, or wings. - The player's permission was removed or expired. Cosmetics are checked each time they are applied, so it disappears on the next join or world change.
A player lost every cosmetic after loading a preset
/cosmetics preset load <name> does not check the preset exists. Loading a misspelled name clears all current selections and still reports "Applied preset". Have them run /cosmetics preset list and load the correct name.
The gadget item doesn't appear
- The player's hotbar is full. They are told to make room; clear a slot and reselect the gadget.
- Gadgets are disabled on this server or in this world.
- The player lacks the gadget's permission.
"Movement gadgets are disabled on this server."
gadgets.allow-movement is false. The Grappling Hook and Balloon are refused; the Firework Launcher and Paint Gun still work.
Right-clicking a pet does nothing
Only the owner can open a pet's editor. Nobody can interact with a pet in any other way: riding, shearing, leashing, trading, bucketing, and feeding are all blocked, for the owner too. If the owner gets "The pet editor is unavailable on this server", the Paper build lacks the Dialog API.
A pet can't be resized as big as expected
The size is clamped to pets.scale.min and pets.scale.max (40% to 160% by default). Players with edeneffects.bypass.pet-scale get the wider bypass range. The pet is re-clamped each time it spawns, so a player who loses the bypass has their pet shrink back. See Pets.
A rank got far more pets than expected
edeneffects.pet.* grants every mob in the game, not a short list. Grant individual pet nodes for lower tiers. See Permissions.
FAQ
Do players lose their selection when a server disables a type?
No. Disabling only stops it showing on that server. Nothing in MySQL changes, and players are not told, so crossing several servers does not produce a stream of messages.
Can I add my own cosmetics?
Not through config. Trails, hats, wings, gadgets, and effects are defined in code; see Cosmetics. Pets are the exception: the list comes from the server's own entity types, so new mobs appear on their own.
Can hostile mobs really be pets?
Yes. Everything that makes them dangerous is cancelled, and they are marked to survive Peaceful difficulty. A few mobs are left out because their behaviour cannot be made harmless; see Pets.
Does EdenEffects work on a single server without Velocity?
It needs MySQL and a server-id, but the proxy plugin is only needed to sync between backends. A single Paper server with MySQL works; there is just no one to send change messages to.
How do I reload the config?
There is no reload command. Restart the server.
Is it safe to use /reload?
EdenEffects handles players already online when it enables, and removes pets, gadget blocks, and plugin items when it disables. A full restart is still recommended, as it is for most plugins.
Does a crash leave pets or painted blocks behind?
Pets, no: leftover pets are removed as soon as their chunk loads. Painted blocks from the last 15 seconds before a crash, yes, since pending restores are held in memory. See Gadgets.
Why is the Thunder death effect still loud with sounds off?
effects.sounds silences cosmetic sounds, but Thunder's flash carries vanilla's own thunder sound, which that setting does not cover. Disable cosmetics.deaths in worlds where it is a problem, or do not grant the node.
What does edeneffects.use do?
Nothing yet. It is declared with a default of true, but the menu does not check it.