Troubleshooting

Troubleshooting

This guide helps you resolve common issues with the Custom Commands plugin. If you encounter problems not covered here, join our Discord server for support.

Common Issues

Plugin Won’t Load

Problem

The plugin doesn’t appear in /plugins list or shows errors in console.

Solutions

1. Check Server Software

   • Ensure you’re using Paper, Spigot, or Bukkit
   • Verify your server software is up to date
   • Check if you’re using the correct version

2. Check Java Version

   • Custom Commands requires Java 17 or higher
   • Update Java if necessary
   • Verify Java version: java -version

3. Check Plugin File

   • Ensure the .jar file is in the plugins folder
   • Verify the file isn’t corrupted
   • Download the plugin again if needed

4. Check Console Errors

   • Look for error messages in server console
   • Check for missing dependencies
   • Verify plugin compatibility

Error Messages

[ERROR] Could not load 'plugins/CustomCommands-1.0.0.jar' in folder 'plugins'

Solution: Check if the file is corrupted or incompatible with your server version.

[ERROR] java.lang.UnsupportedClassVersionError

Solution: Update Java to version 17 or higher.

Commands Not Working

Problem

Custom commands don’t respond when used.

Solutions

1. Check Plugin Status

   /plugins

   Ensure Custom Commands is enabled.

2. Check Command Configuration

   • Verify commands are enabled in config.yml
   • Check for YAML syntax errors
   • Use /customcommands reload after changes

3. Check Permissions

   • Verify players have correct permissions
   • Check permission plugin is working
   • Test with OP permissions

4. Check Console for Errors

   • Look for error messages in console
   • Check log files for detailed errors
   • Enable debug mode for more information

Debug Steps

# Enable debug mode
# In config.yml:
debug:
  enabled: true
  console: true
  file: true

# Reload configuration
/customcommands reload

# Test commands
/discord
/website
/rules

Permission Issues

Problem

Players get “no permission” messages.

Solutions

1. Check Permission Nodes

   • Verify permission format: customcommands.commandname
   • Check for typos in permission names
   • Ensure permissions are set correctly

2. Check Permission Plugin

   • Verify your permission plugin is working
   • Test with /lp user <player> permission check customcommands.discord
   • Check for conflicting permission plugins

3. Check Player Permissions

   • Ensure player has the correct permissions
   • Check group memberships
   • Verify permission inheritance

4. Test with OP

   • Give player OP temporarily
   • Test if commands work with OP
   • This helps isolate permission issues

Permission Examples

# With LuckPerms
/lp user PlayerName permission set customcommands.discord true

# With PermissionsEx
/pex user PlayerName add customcommands.discord

# With GroupManager
/manuaddp PlayerName customcommands.discord

Configuration Errors

Problem

Configuration files have errors or won’t load.

Solutions

1. Check YAML Syntax

   • Verify proper indentation (use spaces, not tabs)
   • Check for missing quotes around strings
   • Ensure proper list formatting

2. Validate Configuration

   • Use online YAML validators
   • Check for duplicate keys
   • Verify proper structure

3. Backup and Restore

   • Keep backups of working configurations
   • Restore from backup if needed
   • Test changes incrementally

4. Check File Permissions

   • Ensure server can read/write config files
   • Check file ownership
   • Verify file permissions

Common YAML Errors

# Wrong - missing quotes
permission: customcommands.discord

# Correct
permission: "customcommands.discord"

# Wrong - incorrect indentation
commands:
discord:
  permission: "customcommands.discord"

# Correct
commands:
  discord:
    permission: "customcommands.discord"

Reload Issues

Problem

/customcommands reload fails or doesn’t work.

Solutions

1. Check Configuration Files

   • Verify config.yml and messages.yml are valid
   • Check for syntax errors
   • Ensure files are not corrupted

2. Check File Permissions

   • Ensure server can read config files
   • Check file ownership
   • Verify write permissions

3. Check Console for Errors

   • Look for error messages during reload
   • Check log files for details
   • Enable debug mode for more information

4. Restart Server

   • If reload continues to fail, restart the server
   • This will load the configuration from scratch
   • Check if the issue persists

Reload Debug

# Enable debug mode
debug:
  enabled: true
  console: true
  file: true

# Try reload
/customcommands reload

# Check console output
# Look for error messages

Console Command Issues

Problem

Console commands in custom commands don’t execute.

Solutions

1. Check Command Syntax

   • Verify console command format
   • Check for proper variable usage
   • Ensure commands are valid

2. Check Variables

   • Verify variable names: {player}, {world}, {x}, {y}, {z}
   • Check for typos in variable names
   • Test with simple commands first

3. Check Permissions

   • Console commands run with console privileges
   • Verify the commands are valid
   • Test commands manually in console

4. Check Command Format

   • Ensure proper JSON format for complex commands
   • Check for proper escaping
   • Test with simple commands first

Console Command Examples

# Simple command
console_commands:
  - "say {player} used the command!"

# JSON command
console_commands:
  - "tellraw {player} [\"\",{\"text\":\"Hello \",\"color\":\"yellow\"},{\"text\":\"{player}\",\"color\":\"green\"}]"

# Effect command
console_commands:
  - "effect give {player} minecraft:glowing 10 1 true"

Performance Issues

Problem

Plugin causes server lag or performance issues.

Solutions

1. Check Console Commands

   • Limit the number of console commands
   • Avoid heavy operations in console commands
   • Use appropriate cooldowns

2. Check Cooldowns

   • Set appropriate cooldowns for commands
   • Prevent command spam
   • Use longer cooldowns for heavy commands

3. Check Debug Mode

   • Disable debug mode in production
   • Reduce logging if not needed
   • Check log file sizes

4. Check Resource Usage

   • Monitor server resources
   • Check for memory leaks
   • Optimize configuration

Performance Tips

# Disable debug in production
debug:
  enabled: false
  console: false
  file: false

# Set appropriate cooldowns
cooldown: 5  # 5 second cooldown

# Limit console commands
console_commands:
  - "say {player} used command"  # Simple command
  # Avoid heavy operations

Debug Information

Enable Debug Mode

# In config.yml
debug:
  enabled: true
  console: true
  file: true

Check Logs

plugins/CustomCommands/logs/latest.log

Test Commands

# Test main command
/customcommands help

# Test reload
/customcommands reload

# Test custom commands
/discord
/website
/rules

Check Permissions

# With LuckPerms
/lp user <player> permission check customcommands.discord

# With PermissionsEx
/pex user <player> check customcommands.discord

Getting Help

Before Asking for Help

1. Check this guide - Look for your issue here first
2. Enable debug mode - Get detailed error information
3. Check logs - Look for error messages
4. Test with OP - See if it’s a permission issue
5. Try reload - Use /customcommands reload

When Asking for Help

Provide this information:

1. Server software and version (Paper, Spigot, etc.)
2. Java version (java -version)
3. Plugin version (from /customcommands version)
4. Error messages (from console and logs)
5. Configuration (relevant parts of config.yml)
6. Steps to reproduce (what you did to cause the issue)

Support Channels

• Discord Server: https://discord.gg/2qCMn6KHj4
• Bug Reports: Use the bug report channel in Discord
• Feature Requests: Use the feature request channel in Discord

Useful Commands

# Check plugin status
/plugins

# Check version
/customcommands version

# Reload configuration
/customcommands reload

# Check help
/customcommands help

# Check support
/customcommands support

Prevention Tips

Best Practices

1. Test Changes - Always test changes on a test server first
2. Backup Configs - Keep backups of working configurations
3. Use Version Control - Track configuration changes
4. Monitor Logs - Regularly check log files
5. Update Regularly - Keep the plugin updated

Configuration Tips

1. Use Comments - Add comments to explain complex configurations
2. Validate YAML - Use YAML validators before applying changes
3. Test Incrementally - Make small changes and test each one
4. Document Changes - Keep track of what you changed and why

Maintenance

1. Regular Backups - Backup configurations regularly
2. Log Rotation - Monitor log file sizes
3. Performance Monitoring - Watch for performance issues
4. Security Updates - Keep server and plugins updated

---

title: Troubleshooting

Quick Reference

Essential Commands

/customcommands help     # Show help
/customcommands reload   # Reload configuration
/customcommands version  # Show version
/customcommands support  # Show support info

File Locations

plugins/CustomCommands/config.yml    # Main configuration
plugins/CustomCommands/messages.yml  # Messages
plugins/CustomCommands/logs/         # Log files

Common Issues

• Plugin won’t load → Check Java version and server software
• Commands not working → Check permissions and configuration
• Permission denied → Check permission nodes and plugin
• Reload fails → Check configuration syntax and file permissions

---

Need more help? Join our Discord server for support and updates!