🔧Troubleshooting Guide

Solutions to common problems and errors with BlackMarket.

Quick Diagnostics

Step 1: Check Plugin Status

/plugins

BlackMarket should be GREEN

Step 2: Check Plugin Info

/bma info

Verify all systems show correctly:

• Version

• Economy provider

• Database type

• Server type

Step 3: Enable Debug Mode

/bma debug

Check console for detailed logs.

Step 4: Check Logs

logs/latest.log

Look for [BlackMarket] entries with errors.

---

Installation Issues

Plugin Won't Load

Symptoms:

• Plugin shows RED in /plugins

• Errors on server startup

• Commands don't work

Solutions:

1. Check server version:

/version

# BlackMarket requires 1.16.5+

1. Check dependencies:

/plugins

# Required: Economy plugin (Vault, PlayerPoints, etc.)

1. Check for errors:

# In logs/latest.log
[ERROR] Could not load 'plugins/BlackMarket.jar'

1. Verify JAR file:

# Check file isn't corrupted
ls -lh plugins/BlackMarket.jar

# Re-download if needed

1. Check permissions:

# File must be readable
chmod 644 plugins/BlackMarket.jar

---

Configuration Issues

YAML Syntax Errors

Symptoms:

• Plugin won't reload

• Failed to load configuration

• Items not appearing

Solutions:

1. Validate YAML syntax:

   • Use YAML Lint

   • Paste your config

   • Fix reported errors

2. Common mistakes:

# ❌ Wrong - Missing quotes
prefix: %prefix% <red>Error

# ✅ Correct - Quoted
prefix: "%prefix% <red>Error</red>"

# ❌ Wrong - Wrong indentation
items:
diamond_sword:
  price: 1000

# ✅ Correct - Proper indentation
items:
  diamond_sword:
    price: 1000

# ❌ Wrong - Tab characters
	material: "DIAMOND"  # Uses tab

# ✅ Correct - Spaces only
  material: "DIAMOND"  # Uses 2 spaces

1. Reset to default:

# Backup current config
mv config.yml config.yml.backup

# Delete items.yml to regenerate
rm items.yml

# Restart server (generates new defaults)

Config Not Updating

Problem: Changes don't apply after editing

Solutions:

1. Reload config:

/bma reload

1. Check file saved:

   • Ensure you saved the file

   • Check file timestamp

2. Clear server cache:

/stop
# Delete server cache
# Start server

1. Verify correct file:

plugins/BlackMarket/config.yml  # ✅
config/BlackMarket/config.yml   # ❌ Wrong location

---

Economy Issues

No Economy Found

Error: No economy plugin found!

Solutions:

1. Install economy plugin:

   • Download Vault + EssentialsX

   • OR PlayerPoints

   • OR CoinsEngine

   • Place in plugins folder

2. Check loaded:

/plugins

# Must see: Vault, PlayerPoints, or CoinsEngine (GREEN)

1. Restart server:

/stop
# Start server

1. Verify detection:

/bma info
# Should show: Economy: [Plugin Name]

Wrong Economy Used

Problem: Item charges from wrong economy

Solutions:

1. Specify economy type:

# items.yml
my_item:
  economy-type: "vault"  # Explicitly set

1. Check default:

# config.yml
economy:
  default: "vault"  # Set your preferred default

1. Verify available:

/bma debug
# Check which economies are detected

Insufficient Funds Not Working

Problem: Can buy with $0

Solutions:

1. Check price set:

my_item:
  price: 1000  # Must be > 0

1. Verify economy plugin works:

/balance
# Should show your money

1. Test economy:

/eco give YourName 1000
/blackmarket
# Try buying item

---

Database Issues

Database Connection Failed

Error: Failed to connect to database!

For SQLite:

1. Check file permissions:

ls -l plugins/BlackMarket/database.db
# Should be readable/writable

1. Check disk space:

df -h
# Ensure space available

1. Delete and regenerate:

# Backup first!
cp database.db database.db.backup
rm database.db
# Restart server

For MySQL:

1. Test connection:

mysql -h localhost -u blackmarket -p blackmarket

1. Check credentials:

# config.yml
database:
  mysql:
    username: "correct_username"
    password: "correct_password"

1. Verify MySQL running:

systemctl status mysql
# or
systemctl status mariadb

1. Check firewall:

telnet mysql-host 3306

1. Grant permissions:

GRANT ALL PRIVILEGES ON blackmarket.* TO 'blackmarket'@'localhost';
FLUSH PRIVILEGES;

Database Locked (SQLite)

Error: Database is locked

Solutions:

1. Stop server completely:

/stop
# Wait for full shutdown

1. Check processes:

lsof | grep database.db
# Kill any lingering processes

1. Restart server:

start

---

GUI Issues

Items Not Showing

Problem: Market GUI opens but no items appear

Solutions:

1. Check items configured:

# items.yml
items:
  diamond_sword:  # Must have at least one item
    material: "DIAMOND_SWORD"
    price: 1000

1. Verify slots configured:

# config.yml
gui:
  market-item-slots:
    - 10
    - 11
    # ... more slots

1. Check items-per-reset:

# config.yml
market:
  items-per-reset: 5  # Must be > 0

1. Force market reset:

/bma reset

1. Check item chances:

# items.yml
diamond_sword:
  chance: 100  # 0 = never appears!

GUI Buttons Not Working

Problem: Clicking buttons does nothing

Solutions:

1. Check action configured:

# config.yml
gui:
  items:
    close:
      action: "close"  # Must have action

1. Verify slot correct:

close:
  slot: 53  # Must be valid slot (0-53)

1. Test in vanilla:

   • Remove other GUI plugins

   • Test if issue persists

2. Check for conflicts:

/plugins
# Disable other shop plugins temporarily

Wrong GUI Size

Problem: GUI too big/small

Solutions:

1. Check size setting:

# config.yml
gui:
  rows: 6  # Valid: 1-6
  # OR
  size: 54  # Valid: 9, 18, 27, 36, 45, 54

1. Ensure multiple of 9:

# ❌ Wrong
size: 50

# ✅ Correct
size: 54

1. Adjust market slots:

# Ensure slots fit in GUI size
# For 54-slot GUI, use slots 0-53
market-item-slots:
  - 10
  - 11
  # Don't use slot 54+!

---

Purchase Issues

Can't Buy Items

Problem: Clicking items does nothing

Solutions:

1. Check permission:

/lp user YourName permission check blackmarket.use

1. Check item permission:

# items.yml
legendary_item:
  permission: "blackmarket.buy.legendary"
  # Give permission:
  # /lp user YourName permission set blackmarket.buy.legendary

1. Check stock:

# items.yml
my_item:
  stock: 10  # If sold out, can't buy

# Check if sold out
/bma info

1. Check cooldown:

my_item:
  cooldown: "1h"  # May still be on cooldown

1. Check one-time:

my_item:
  one-time: true  # Can only buy once

Purchase But No Item

Problem: Money deducted but no item received

Solutions:

1. Check command:

# items.yml
my_item:
  command: "give %player% diamond_sword 1"
  # Ensure command is correct

1. Test command manually:

/give YourName diamond_sword 1
# Does it work?

1. Check console errors:

# In logs after purchase
[BlackMarket] Error executing command: ...

1. Verify command format:

# ✅ Correct
command: "give %player% diamond 1"

# ❌ Wrong (typo)
command: "give %plyer% diamond 1"

Infinite Purchases

Problem: Can buy item repeatedly without cooldown

Solutions:

1. Set cooldown:

my_item:
  cooldown: "1h"  # Prevent spam

1. Set one-time:

my_item:
  one-time: true  # Only once ever

1. Set stock:

my_item:
  stock: 10  # Limited quantity

---

Redis Issues

Redis Connection Failed

Error: Failed to initialize Redis

Solutions:

1. Check Redis running:

sudo systemctl status redis-server

1. Test connection:

redis-cli -h localhost -p 6379 -a password ping
# Should return: PONG

1. Check password:

# config.yml
redis:
  password: "correct_password"

1. Check firewall:

telnet redis-host 6379

1. Verify port:

redis:
  port: 6379  # Default

Cross-Server Not Syncing

Problem: Changes on one server don't appear on others

Solutions:

1. Check unique server IDs:

# Each server must be different!
# Server 1
redis:
  server-id: "lobby-1"

# Server 2
redis:
  server-id: "survival-1"

1. Verify all connected:

# On each server
/bma info
# Should show: Redis: ENABLED

1. Check same Redis instance:

# All servers must use SAME Redis
redis:
  host: "same-redis-host"
  port: 6379
  database: 0  # Same database number

1. Enable debug:

/bma debug
# Check console for Redis messages

---

Message Issues

Colors Not Showing

Problem: Messages show <red> literally

Solutions:

1. Enable MiniMessage:

# config.yml
messages:
  use-minimessage: true

1. Reload messages:

/bma reload messages

1. Use legacy codes instead:

# messages.yml
prefix: "&6[Shop] &7»"  # Use & codes

Prefix Not Working

Problem: %prefix% shows literally in messages

Solutions:

1. Quote messages:

# ❌ Wrong
no-permission: %prefix% <red>Error

# ✅ Correct
no-permission: "%prefix% <red>Error</red>"

1. Define prefix:

# Must be defined in messages file
prefix: "<gold>[Shop]</gold>"

1. Reload:

/bma reload messages

Language File Not Loading

Problem: Changed language but messages stay English

Solutions:

1. Check filename:

# config.yml
messages:
  lang: "ES_ES"  # Must match filename exactly!

# File must be:
plugins/BlackMarket/lang/ES_ES.yml
# NOT: es_es.yml or spanish.yml

1. Enable localization:

messages:
  localization: true  # Must be enabled!
  lang: "ES_ES"

1. Reload:

/bma reload messages

---

Performance Issues

Lag on Market Open

Problem: Server lags when opening GUI

Solutions:

1. Reduce items-per-reset:

market:
  items-per-reset: 5  # Lower = less lag

1. Disable effects:

# items.yml - Remove from all items
# effect: "VILLAGER_HAPPY"

1. Use MySQL instead of SQLite:

database:
  type: "mysql"

1. Optimize database:

# MySQL
OPTIMIZE TABLE player_data, player_purchases;

# SQLite
sqlite3 database.db "VACUUM;"

Slow Database Queries

Problem: Delayed responses to commands

Solutions:

1. Check database size:

# MySQL
SELECT table_name, 
       ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
FROM information_schema.tables
WHERE table_schema = 'blackmarket';

1. Optimize tables:

OPTIMIZE TABLE player_data, player_purchases, purchase_history;

1. Add indexes (for large databases):

CREATE INDEX idx_uuid ON player_purchases(uuid);
CREATE INDEX idx_timestamp ON purchase_history(timestamp);

1. Clean old data:

# Delete old purchase history (keep last 30 days)
DELETE FROM purchase_history 
WHERE timestamp < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY)) * 1000;

---

Common Error Messages

ClassNotFoundException

Error: java.lang.ClassNotFoundException: ...

Cause: Missing dependency

Solution: Install required plugin (Vault, PlayerPoints, etc.)

NullPointerException

Error: java.lang.NullPointerException at ...

Causes:

1. Invalid item configuration

2. Missing required field

3. Corrupted database

Solutions:

1. Check item has all required fields

2. Validate YAML syntax

3. Regenerate database

IllegalArgumentException

Error: java.lang.IllegalArgumentException: Invalid material

Cause: Invalid material name

Solution: Fix material name

# ❌ Wrong
material: "DIAMONDSWORD"

# ✅ Correct
material: "DIAMOND_SWORD"

---

Getting Help

Before Asking for Support

1. ✅ Check this troubleshooting guide

2. ✅ Read the FAQ

3. ✅ Enable debug mode: /bma debug

4. ✅ Check logs/latest.log for errors

5. ✅ Test with minimal plugins (disable others)

6. ✅ Verify you're on latest BlackMarket version

Providing Information

When asking for help, include:

1. Server information:

/version
# Paste output

1. Plugin version:

/bma info
# Paste output

1. Error logs:

# From logs/latest.log
# Include full stack trace

1. Configuration:

# Paste relevant config sections
# Remove sensitive info (passwords)

1. Steps to reproduce:

• What did you do?

• What happened?

• What did you expect?

Support Channels

• Discord: Support Server

• BuiltByBit: Plugin Page

• GitHub Issues: Report bugs

---

Next Steps

• Check FAQ

• Review configuration guide

• Learn about commands