Troubleshooting

Common issues and solutions for PrimeChat plugin problems.

Installation Issues

Plugin Not Loading

Symptoms

  • Plugin doesn't appear in /plugins list

  • No PrimeChat folder created in plugins directory

  • Console shows plugin loading errors

Solutions

  1. Check Server Version

    Ensure your server is running Minecraft 1.19 or higher
PrimeChat requires API version 1.19+

  2. Verify Java Version

    PrimeChat requires Java 8 or higher
Check with: java -version

  3. Check Console for Errors

    Look for red error messages during server startup
Common causes: missing dependencies, corrupted JAR file

  4. File Permissions

    Ensure server has read/write access to plugins folder
Check file permissions on Linux/Mac systems

Configuration Loading Errors

Symptoms

  • "Failed to load config.yml" messages

  • Plugin reverts to default settings

  • YAML parsing errors in console

Solutions

  1. YAML Syntax Validation

    # Use online YAML validator to check syntax
# Common issues:
# - Missing quotes around special characters
# - Incorrect indentation (use spaces, not tabs)
# - Missing colons after keys

  2. Backup and Reset

    1. Stop server
2. Backup current config files
3. Delete config.yml
4. Restart server (generates new config)
5. Reapply your settings carefully

  3. Character Encoding

    Ensure config files are saved in UTF-8 encoding
Avoid special characters in file editors

Chat Format Issues

Colors Not Displaying

Symptoms

  • Color codes showing as plain text (&c, &#FF0000)

  • Hex colors not working

  • Gradients appearing as regular text

Diagnosis Steps

  1. Check Client Version

    Hex colors require Minecraft 1.16+ clients
Legacy codes (&c) work on all versions

  2. Verify Permissions

    /lp user <player> permission check primechat.color
/lp user <player> permission check primechat.hex
/lp user <player> permission check primechat.gradient

  3. Test Format Syntax

    # Correct hex format
color: "&#FF0000"

# Incorrect formats
color: "#FF0000"   # Missing &
color: "&xFF0000"  # Wrong prefix

Solutions

  1. Grant Proper Permissions

    /lp user <player> permission set primechat.color true
/lp user <player> permission set primechat.hex true

  2. Update Client Version

    Hex colors and gradients require Minecraft 1.16+
Use legacy codes for older clients

  3. Check Format Syntax

    # Correct formats
legacy: "&cRed text"
hex: "&#FF0000Red text"
gradient: "<#FF0000>Red to Blue</#0000FF>"

PlaceholderAPI Issues

Symptoms

  • Placeholders showing as %placeholder% in chat

  • "PlaceholderAPI not found" warnings

  • Inconsistent placeholder replacement

Solutions

  1. Install PlaceholderAPI

    1. Download PlaceholderAPI from Spigot
2. Install required expansions:
   /papi ecloud download Vault
   /papi ecloud download Player
   /papi reload

  2. Verify Expansions

    /papi list
# Should show installed expansions
# Common ones: Vault, Player, LuckPerms

  3. Test Placeholders

    /papi parse <player> %vault_rank%
/papi parse <player> %player_name%

  4. Check Dependencies

    Ensure required plugins are installed:
- Vault (for economy/permissions)
- LuckPerms (for permissions)
- EssentialsX (for player data)

Security Feature Issues

Anti-Spam Not Working

Symptoms

  • Players can spam messages

  • No cooldown warnings shown

  • Bypass permissions not working

Solutions

  1. Check Configuration

    security:
  anti-spam:
    enabled: true
    cooldown: 3

  2. Verify Permissions

    # Players should NOT have bypass by default
primechat.bypass.spam: false

# Only grant to trusted users
/lp user <vip> permission set primechat.bypass.spam true

  3. Check Event Priority

    Ensure no other plugins are cancelling chat events
Check plugin load order in startup logs

Blocked Words Not Filtering

Symptoms

  • Inappropriate words getting through

  • Filter not triggering

  • Players with bypass sending blocked words

Solutions

  1. Review Word List

    security:
  blocked-words:
    enabled: true
    words:
      - "badword"
      - "inappropriate"

  2. Case Sensitivity

    PrimeChat filters are case-insensitive
Add variations if needed:
- "badword"
- "BadWord"
- "BADWORD"

  3. Check Bypass Permissions

    /lp user <player> permission check primechat.bypass.blockedwords
Only staff should have this permission

Anti-Advertising False Positives

Symptoms

  • Legitimate messages being blocked

  • IP addresses in coordinates blocked

  • Domain names in discussion blocked

Solutions

  1. Configure Detection Scope

    security:
  anti-advertising:
    detection:
      chat: true
      commands: false  # Disable if causing issues
      signs: false     # Disable if too strict

  2. Add Whitelist

    security:
  anti-advertising:
    whitelist:
      - "youtube.com"
      - "discord.gg"
      - "imgur.com"

  3. Grant Bypass Permissions

    /lp group staff permission set primechat.bypass.advertising true

Private Messaging Problems

Messages Not Delivering

Symptoms

  • /msg command not working

  • "Player not found" errors

  • Messages not reaching recipients

Solutions

  1. Check Command Registration

    # In plugin.yml, verify commands are registered
commands:
  message:
    aliases: [msg, tell, w]

  2. Test Player Names

    Use tab completion for player names
Check for exact spelling
Ensure target player is online

  3. Review Configuration

    private-messaging:
  sender-format: "&#FF69B4&o(To %receiver%)&r&#D3D3D3: %message%"
  receiver-format: "&#FF69B4&o(From %sender%)&r&#D3D3D3: %message%"

Reply System Not Working

Symptoms

  • /r command shows "no one to reply to"

  • Reply mapping not updating

  • Conversations not remembered

Solutions

  1. Check Recent Conversations

    Reply system requires recent message exchange
Mapping clears after server restart (by default)

  2. Enable Persistent Replies

    private-messaging:
  persistent-replies: true

  3. Clear Reply Cache

    /chat reload
# This clears reply mappings

Chat Games Issues

Games Not Sending

Symptoms

  • No trivia questions appearing

  • Manual /chat chatgames not working

  • Auto-send not functioning

Solutions

  1. Check Configuration

    # In chatgames.yml
games:
  enabled: true
  auto-send:
    enabled: true
    interval: 300

  2. Verify Question Format

    questions:
  example:
    question: "What is 2+2?"
    answers:
      - "4"
      - "four"
    reward-command: "give %player% diamond 1"
    reward-display: "1x Diamond"

  3. Check Permissions

    /lp user <admin> permission check primechat.chatgames

Rewards Not Working

Symptoms

  • Winners not receiving rewards

  • Console command errors

  • Invalid reward commands

Solutions

  1. Test Commands Manually

    /give PlayerName diamond 1
/eco give PlayerName 100

  2. Check Command Syntax

    reward-command: "give %player% diamond 1"
# Not: "give {player} diamond 1"
# Not: "give $player diamond 1"

  3. Verify Plugin Integration

    Ensure required plugins are installed:
- Essentials (for /give)
- Vault + Economy plugin (for /eco)

Performance Issues

Server Lag During Chat

Symptoms

  • TPS drops when players chat

  • Console spam during high activity

  • Memory usage increasing

Solutions

  1. Enable Async Processing

    performance:
  async-processing: true
  max-players-per-tick: 50

  2. Optimize Placeholders

    placeholderapi:
  cache:
    enabled: true
    duration: 30

  3. Reduce Complex Formatting

    Limit gradient usage
Cache color processing
Simplify hover text

Memory Leaks

Symptoms

  • RAM usage continuously increasing

  • Server crashes with OutOfMemoryError

  • Performance degradation over time

Solutions

  1. Enable Auto-Cleanup

    performance:
  memory:
    auto-cleanup: true
    cleanup-interval: 30

  2. Monitor Memory Usage

    Use /spark profiler to identify memory usage
Check for accumulating data structures

  3. Restart Schedule

    Implement regular server restarts
Clear accumulated cache periodically

Database Issues

Connection Failures

Symptoms

  • "Database connection failed" errors

  • Plugin disabling on startup

  • Data not persisting

Solutions

  1. Check Database Configuration

    database:
  type: "sqlite"  # or "mysql"
  sqlite:
    file: "primechat.db"

  2. Verify File Permissions

    Ensure server can read/write database file
Check folder permissions on Linux/Mac

  3. MySQL Connection Issues

    mysql:
  host: "localhost"
  port: 3306
  database: "primechat"
  username: "correct_user"
  password: "correct_password"

Integration Problems

Vault Integration

Symptoms

  • Rank placeholders not working

  • Economy integration failing

  • Permission system not detected

Solutions

  1. Install Vault

    Download Vault from Spigot
Restart server after installation

  2. Install Compatible Plugins

    Permission plugin: LuckPerms, PermissionsEx, GroupManager
Economy plugin: EssentialsX, CMI, iConomy

  3. Test Vault Integration

    /vault-info
# Should show connected permission/economy plugins

LuckPerms Issues

Symptoms

  • Permissions not working

  • Groups not displaying correctly

  • Inheritance problems

Solutions

  1. Check Permission Nodes

    /lp user <player> permission check primechat.color
/lp group <group> permission set primechat.hex true

  2. Verify Group Setup

    /lp group <group> info
/lp user <player> parent info

  3. Clear Cache

    /lp reloadconfig
/lp group <group> clear

Getting Additional Help

Debug Information

Enable debug mode for detailed logging:

debug:
  enabled: true
  chat-processing: true
  security-checks: true
  placeholder-api: true

Log Analysis

Check these log locations:

  • Server Console: Real-time error messages

  • Latest.log: Recent server activity

  • PrimeChat Logs: Plugin-specific logs in /plugins/PrimeChat/logs/

Premium Support

As a premium plugin owner (£14.99 GBP), you have access to:

  1. Discord Server: https://discord.gg/XTcKTG6vZP - Priority support for customers

  2. Documentation: This comprehensive GitBook

  3. Direct Developer Contact: Available for premium customers

Information to Include

When seeking help, provide:

  • Purchase Verification: Confirm you're a legitimate customer

  • Server Version: Spigot/Paper version

  • Plugin Version: PrimeChat version

  • Java Version: Java runtime version

  • Error Messages: Complete error logs

  • Configuration: Relevant config sections

  • Steps to Reproduce: How to trigger the issue

PreviousColor & Formatting

Last updated