Troubleshooting

Solutions to common problems and issues with AnnouncementGUI.

🔍 Quick Diagnosis

Is the plugin loaded?

Check:

/plugins

Look for: AnnouncementGUI in green

If red or missing:

1

Check server version

Required: Paper 1.21+ or Folia

• Run: /version

• If incompatible, update to Paper 1.21+ or download a compatible plugin version

2

Check Java version

Required: Java 17+

• Run:

java -version

• If outdated, install Java 17+ and update server startup script

3

Check console for errors during startup

• Inspect server logs for plugin loading errors and stack traces

• Fix any errors reported and restart

Can you access the GUI?

Try:

/announcegui

If permission error:

• Grant announcegui.admin permission

• Check if you have OP status

If command not found:

• Plugin not loaded (see above)

• Check plugin.yml is intact

Are announcements running?

Check:

1

Open the GUI and edit the announcement

• GUI → Edit → Select announcement

2

Verify status

• Ensure "Status: Enabled" (✓)

3

Check interval

• Ensure an interval is set and wait at least one interval period

4

Check target server

• Verify the target server matches the current server

---

🚫 Installation Issues

Plugin doesn't load

Symptom: Plugin not in /plugins list or shows red

Possible Causes:

1. Incompatible Server Version

Error: Could not load plugin 'AnnouncementGUI'... Unsupported API version

Solution:

Check server version: /version
Required: Paper 1.21+ or Folia

Fix:

• Update to Paper 1.21 or newer

• OR download compatible plugin version

2. Wrong Java Version

Error: Unsupported class file major version

Solution:

# Check Java version
java -version

# Required: Java 17 or higher

Fix:

• Install Java 17 or newer

• Update server startup script to use Java 17+

3. Corrupted JAR File

Error: Error loading plugin... invalid JAR

Solution:

• Re-download plugin JAR

• Verify download completed successfully

• Check file size matches expected size

4. Missing Dependencies

Error: NoClassDefFoundError or similar

Solution:

• Ensure Paper/Folia server (not Spigot/Bukkit)

• Paper auto-downloads libraries; ensure internet access

• Check libraries section in plugin.yml

Configuration file errors

Symptom: Plugin loads but doesn't work correctly

Causes:

Invalid YAML Syntax

Error: Could not load config.yml

Solution:

1. Validate YAML:

   • Use YAML Validator

   • Check for tabs (use spaces instead)

   • Check indentation

2. Reset config:

   # Backup first!
   mv plugins/AnnouncementGUI/config.yml plugins/AnnouncementGUI/config.yml.backup
   # Restart server - generates new config

Wrong Configuration Values

Error: Plugin loads but behaves incorrectly

Check:

• localServerId matches intended server

• servers list contains valid IDs

• Storage credentials are correct

• Boolean values are true or false (lowercase, no quotes)

---

🗄️ Database Issues

SQLite Issues

Cannot create database file

Symptom: Failed to initialize SQLite database

Solutions:

1

Check permissions

ls -la plugins/AnnouncementGUI/
# Plugin folder must be writable

2

Fix permissions

chmod -R 755 plugins/AnnouncementGUI/

3

Check disk space

df -h

Database locked error

Symptom: Database is locked

Causes:

• Multiple server instances accessing same database

• File permission issues

• Corrupted database

Solutions:

1. Stop all servers using the database

2. Check for locked files:

   lsof plugins/AnnouncementGUI/announcements.db

3. If corrupted, restore from backup:

   cp announcements.db.backup announcements.db

MySQL Issues

Connection refused

Symptom: Connection refused or Cannot connect to MySQL

Solutions:

1. Test MySQL connection:

   mysql -h <host> -P <port> -u <username> -p
   # Enter password when prompted

2. Check MySQL is running:

   # On MySQL server
   systemctl status mysql
   # or
   systemctl status mysqld

3. Check firewall:

   # On MySQL server
   sudo ufw status
   # Allow from Minecraft server IP
   sudo ufw allow from <mc-server-ip> to any port 3306

4. Check MySQL listening:

   # Should show 0.0.0.0:3306 or :::3306
   netstat -tlnp | grep 3306

   If only shows 127.0.0.1: Edit /etc/mysql/mysql.conf.d/mysqld.cnf:

   # Change from:
   bind-address = 127.0.0.1
   # To:
   bind-address = 0.0.0.0

   Restart MySQL:

   sudo systemctl restart mysql

Access denied

Symptom: Access denied for user 'announcegui'@'host'

Solutions:

1. Verify credentials in config.yml

2. Check user exists:

   SELECT User, Host FROM mysql.user WHERE User='announcegui';

3. Recreate user:

   DROP USER 'announcegui'@'%';
   CREATE USER 'announcegui'@'%' IDENTIFIED BY 'password';
   GRANT ALL PRIVILEGES ON minecraft_announcements.* TO 'announcegui'@'%';
   FLUSH PRIVILEGES;

4. Check host wildcard:

   • 'announcegui'@'%' allows from any host

   • 'announcegui'@'localhost' only allows local

   • 'announcegui'@'192.168.1.%' allows from subnet

Unknown database

Symptom: Unknown database 'minecraft_announcements'

Solutions:

1. Create database:

   CREATE DATABASE minecraft_announcements;

2. Grant permissions:

   GRANT ALL PRIVILEGES ON minecraft_announcements.* TO 'announcegui'@'%';
   FLUSH PRIVILEGES;

---

🎮 GUI Issues

GUI doesn't open

Symptom: /announcegui does nothing or shows permission error

Solutions:

1. Check permission:

   /lp user <username> permission check announcegui.admin

2. Grant permission:

   /lp user <username> permission set announcegui.admin true

3. Check console for errors

4. Verify player (not console):

   • Command requires player

   • Cannot be run from console

Items not clickable

Symptom: Clicking items does nothing

Solutions:

1. Close and reopen GUI:

   • Press ESC

   • Run /announcegui again

2. Check for conflicting plugins:

   • Inventory protection plugins

   • Anti-cheat plugins

   • Other GUI plugins

3. Check console for errors when clicking

4. Try on different client:

   • Test with vanilla client

   • Disable client-side mods

Chat input not working

Symptom: After clicking item, can't type in chat

Solutions:

1. Close all GUIs:

   • Press ESC multiple times

   • Wait a moment

2. Relog:

   • Disconnect and reconnect

   • Clears any stuck states

3. Check for chat plugins:

   • Chat formatting plugins

   • Chat filter plugins

   • May interfere with input

---

📢 Announcement Issues

Announcements not broadcasting

Symptom: Created announcement but no messages appear

Diagnosis Steps:

1

Check announcement status

• GUI → Edit → Select announcement

• Look for "✓ Enabled"

• If "✗ Disabled", click Toggle Status

2

Check target server

• Verify announcement targets current server

• OR targets "ALL" with enableAllServersAnnouncements: true

3

Check interval

• Wait at least one interval period (e.g., 300s = 5 minutes)

4

Check console for errors

• Look for scheduler errors

• Look for broadcast errors

Common Causes:

Wrong Target Server

Example:

• Announcement targets "survival"

• Current server ID is "lobby"

• Solution: Edit announcement, change target to "lobby" or "ALL"

ALL Announcements Disabled

Example:

• Announcement targets "ALL"

• Config has enableAllServersAnnouncements: false

• Solution: Change config to true and restart

Announcement Disabled

Solution:

1. GUI → Edit → Select announcement

2. Click "Toggle Status"

3. Click "Save"

Interval Too Long

Solution:

• Edit announcement

• Set shorter interval for testing (e.g., 60 seconds)

• Save and wait

Announcements broadcasting to wrong servers

Symptom: Announcement shows on wrong server(s)

Solutions:

1. Verify localServerId:

   # Check config.yml on each server
   localServerId: "lobby"  # Must be unique per server

2. Check announcement target:

   • GUI → Edit → Select announcement

   • Verify target matches intended server

3. Check database:

   SELECT id, name, targetServerId FROM announcements;

Announcements not syncing (Multi-Server)

Symptom: Create on Server A, doesn't appear on Server B

Solutions:

1. Wait for polling interval:

   # Check config.yml
   changePollingIntervalSeconds: 10  # Wait at least this long

2. Verify MySQL connection:

   # From each server
   mysql -h <host> -u <username> -p <database>

3. Check same database:

   • All servers must use same MySQL database

   • Verify config.yml on all servers

4. Check console for errors:

   • Look for "Failed to poll changes"

   • Look for MySQL connection errors

5. Restart all servers:

   • Sometimes helps clear sync issues

Formatting not working

Symptom: Color codes or MiniMessage tags show as text

MiniMessage Issues:

Shows: <green>Hello</green> Expected: Green "Hello"

Solutions:

1. Use MiniMessage format:

   • <green>text</green> not &atext

   • <bold>text</bold> not &ltext

2. Check Paper version:

   • MiniMessage requires Paper 1.16.5+

   • Run /version to verify

Legacy Color Code Issues:

Shows: &aHello Expected: Green "Hello"

Solutions:

1. Use correct format:

   • &a for green

   • &c for red

   • etc.

2. Check if disabled:

   • Some servers disable legacy codes

   • Use MiniMessage instead

PlaceholderAPI not working

Symptom: Placeholders show as %player_name% instead of values

Solutions:

1. Install PlaceholderAPI:

   /papi version

   If not found, install PlaceholderAPI plugin

2. Install expansions:

   /papi ecloud download Player
   /papi ecloud download Server
   /papi reload

3. Test placeholder:

   /papi parse me %player_name%

4. Verify expansion:

   /papi list

5. Restart server:

   • PlaceholderAPI requires restart after installation

See: PlaceholderAPI Integration Guide for details

---

⚡ Performance Issues

Server lag with announcements

Symptom: TPS drops when announcements broadcast

Solutions:

1. Check placeholder usage:

   • Placeholders require per-player parsing

   • Use sparingly

   • Increase intervals for placeholder announcements

2. Reduce announcement frequency:

   • Increase intervals

   • Combine multiple announcements into one

3. Optimize messages:

   • Shorter messages

   • Fewer lines

   • Less complex formatting

4. Check database performance:

   • Optimize MySQL tables

   • Increase connection pool

   • Use local MySQL server

High database query count

Symptom: Many MySQL queries in logs

Solutions:

1. Increase polling interval:

   changePollingIntervalSeconds: 30  # Increase from 10

2. Optimize MySQL:

   OPTIMIZE TABLE announcements;
   OPTIMIZE TABLE announcement_changelog;

3. Add indexes:

   -- Usually already exists, but verify:
   SHOW INDEX FROM announcements;

---

🔧 Command Issues

Export fails

Symptom: /announcegui export shows error

Solutions:

1. Check plugin folder writeable:

   ls -la plugins/AnnouncementGUI/
   chmod 755 plugins/AnnouncementGUI/

2. Check disk space:

   df -h

3. Check console for detailed error

Import fails

Symptom: /announcegui import file.json shows error

Solutions:

1. Verify file exists:

   ls -la plugins/AnnouncementGUI/file.json

2. Validate JSON:

   • Use JSONLint

   • Check for syntax errors

   • Ensure valid structure

3. Check file permissions:

   chmod 644 plugins/AnnouncementGUI/file.json

4. Test with small file:

   • Create simple test file

   • Import to verify functionality

---

🔄 Update Issues

Plugin won't update

Symptom: New version not working

Solutions:

1. Complete update process:

   # Stop server
   # Backup plugins/AnnouncementGUI/ folder
   # Replace JAR file
   # Start server

2. Clear old JAR:

   # Remove old version
   rm plugins/AnnouncementGUI-*.jar
   # Add new version
   # Restart

3. Check for config changes:

   • Compare old and new config.yml

   • Update any changed options

   • Keep your customizations

Config resets after update

Symptom: Configuration lost after update

Solutions:

1. Before updating:

   # Backup config
   cp plugins/AnnouncementGUI/config.yml ~/config.yml.backup

2. After updating:

   # If config reset, restore backup
   cp ~/config.yml.backup plugins/AnnouncementGUI/config.yml

3. Merge configs:

   • Compare old and new config.yml

   • Add new options from new config

   • Keep your customizations

---

📊 Diagnostic Commands

Check Plugin Status

# In-game
/plugins

# Console logs
grep "AnnouncementGUI" logs/latest.log

Check Database Connection

# SQLite
ls -la plugins/AnnouncementGUI/announcements.db

# MySQL
mysql -h <host> -u <user> -p<password> -e "USE <database>; SHOW TABLES;"

Check Announcements

-- Connect to MySQL
mysql -h <host> -u <user> -p

-- List announcements
USE minecraft_announcements;
SELECT * FROM announcements;

-- Check specific announcement
SELECT * FROM announcements WHERE name='Welcome Message';

Check Changelog (Multi-Server)

-- View recent changes
SELECT * FROM announcement_changelog ORDER BY change_time DESC LIMIT 10;

---

🆘 Getting Help

Before Asking for Help

1

Plugin version

Run:

/plugins

2

Server version

Run:

/version

3

Config files

Gather: config.yml and any relevant configs (remove secrets)

4

Console logs

# Recent errors
grep -i "error\|exception" logs/latest.log | grep -i "announcement"

5

Steps to reproduce

Write clear steps that show the issue consistently

Where to Get Help

1. Check this guide first

2. Check FAQ

3. Search GitHub Issues

4. Create new issue with gathered information

Creating a Good Bug Report

Include:

• Plugin version and server version

• Description of the problem

• Steps to reproduce

• Expected behavior

• Actual behavior

• Config files (remove passwords!)

• Console errors

• Screenshots if relevant

---

🔧 Advanced Troubleshooting

Enable Debug Logging

Edit: config.yml (if debug option exists)

debug: true

Restart server and check logs for detailed information.

Database Diagnostics

SQLite:

# Check database integrity
sqlite3 plugins/AnnouncementGUI/announcements.db "PRAGMA integrity_check;"

MySQL:

-- Check table status
SHOW TABLE STATUS FROM minecraft_announcements;

-- Check for corrupted tables
CHECK TABLE announcements;
CHECK TABLE announcement_changelog;

-- Repair if needed
REPAIR TABLE announcements;

Thread Dumps

If server freezes during announcements:

# Get process ID
ps aux | grep java

# Generate thread dump
kill -3 <PID>

# Check in logs
grep "Thread dump" logs/latest.log -A 100

---

Related Documentation:

• FAQ - Frequently asked questions

• Configuration Guide - Configuration options

• Installation Guide - Installation steps

• Multi-Server Setup - Multi-server issues