Troubleshooting

Check these first:

• Is PacketEvents installed? ClothesPlus will not load without it.
• Are you running Minecraft 1.20+ on Paper or Spigot?
• Is your Java version 17+? Check with java -version on your host.
• Check the server console at startup for error messages from ClothesPlus.
• Make sure the JAR file isn't corrupted — re-download if needed.

• Restart the server twice — some environments require two boots for license validation.
• Check that license.txt contains only the license key with no extra spaces or line breaks.
• Ensure your server has outbound internet access (the plugin contacts the license server).
• Open a ticket on Discord if the issue persists.

• Verify your MineSkin API key is correctly set in config.yml
• Check the console for MineSkin API rate limit or authentication errors
• Ensure overlay PNG files are valid 64×64 pixel Minecraft skin format
• Try /clothes refresh to force a skin update
• If using base_skin: false, ensure the player's Mojang skin is accessible
• Clear the cache with /clothes cache clear and try again

• All permissions default to op — non-op players need explicit permission grants
• Use LuckPerms: /lp group default permission set wardrobeclothes.use true
• Check the Permissions reference for the exact node you need
• Run /lp user permission check wardrobeclothes.use to verify

• Make sure you have overlay PNGs in the overlays/ subfolders
• Each subfolder (shirts, pants, etc.) becomes a category — they need at least one PNG
• Run /clothes reload after adding new overlays
• Check that your overlays are valid 64×64 PNG files

• Set the camera position: /clothes cursor setcamera
• Make sure creator/settings.yml has enabled: true
• Check that creator overlay folders exist (e.g., overlays/hairs/cursor/)
• Run /clothes cursor reload after making changes
• Verify the player has wardrobeclothes.create permission

• Verify your MySQL host, port, database name, username, and password in config.yml
• Ensure the MySQL user has CREATE, SELECT, INSERT, UPDATE, DELETE privileges
• Check if your host allows remote MySQL connections (if the DB is on a different server)
• Try connecting with the same credentials via a MySQL client to rule out credential issues

• Enable all cache systems in config.yml (shared_cache, creator_cache, base_skin_cache)
• MineSkin API calls are rate-limited — the cache prevents excessive API calls
• Consider upgrading your MineSkin API key tier for higher rate limits
• Run /clothes cache clear if cache data seems stale

• ClothesPlus automatically reapplies skins 1 second after joining, and again at 3 seconds as a backup
• If using SkinsRestorer or similar plugins, they may conflict — ensure ClothesPlus loads after them
• Check if overlays are stored in database (if MySQL is enabled) or in the data/overlays/ folder
• Try /clothes cache clear if experiencing issues
• Run /overlays to manually reapply your skin if needed

• Ensure scale-system-enabled: true in creator/settings.yml
• The scale attribute requires Minecraft 1.20.5+ — on older versions the menu appears but height doesn't change
• If the scale section is missing from your config, it will be auto-injected on next startup or /clothes reload
• Check console for "Scale attribute not available" — this means your server version is too old
• If scale values are lost after /clothes cursor regenerate, update to v3.0.3+
• The NPC preview should reflect height changes in real-time — if not, check PacketEvents is up to date

• Overlays must be 64×64 pixels in standard Minecraft skin format
• Transparent pixels show the base skin underneath — make sure unwanted areas are fully transparent
• If colors look off, check that you're not using a grayscale overlay without proper tint configuration
• Use the Skin Editor to preview and validate your overlays