Troubleshooting Guide

This guide covers common issues and their solutions when using Showcase mod. Most problems can be resolved by following these troubleshooting steps.

Installation Issues

Mod Not Loading

Solutions:

1. Check Minecraft Version:

   Showcase 2.3.1+mc1.21.6 requires Minecraft 1.21.6
   Use the correct version for your server

2. Verify Dependencies:

   • ✅ Fabric Loader installed
   • ✅ Fabric API (correct version)
   • ✅ Java 21+ for MC 1.21.x

3. Check Installation Path:

   server/
   ├── mods/
   │   ├── fabric-api-[version].jar     ✅
   │   ├── showcase-[version].jar       ✅
   │   └── other-mods.jar
   └── server.jar

4. Review Server Logs:

   grep -i "showcase" logs/latest.log
   grep -i "error" logs/latest.log

Fabric API Conflicts

Fix: Download the correct Fabric API version from Modrinth.

Permission Issues

Commands Not Working

/lp info

# For all players
/lp group default permission set showcase.command.item true

# For specific player
/lp user PlayerName permission set showcase.command.inventory true

/lp user PlayerName permission check showcase.command.item

# Grant OP status
/op PlayerName

# Check OP level
/list ops

# config/showcase/config.yml
debug:
  enabled: true
  logPermissions: true

/showcase-manage perms PlayerName

grep "PERMISSION" logs/latest.log

Chat Keywords Not Working

Diagnostic Steps:

1. Check Configuration:

   chatKeywords:
     enabled: true  # Must be true

2. Verify Permissions:

   showcase.chat.item

   Required for [item] keyword

3. Check Rate Limits:

   chatKeywords:
     rateLimitPerMinute: 5
     rateLimitPerHour: 30

4. Test with Debug:

   debug:
     logChatKeywords: true

Configuration Problems

Config File Not Loading

Solutions:

1. Check YAML Syntax:

   # Use a YAML validator
   yamllint config/showcase/config.yml

2. Verify File Permissions:

   ls -la config/showcase/
   # Server must have read/write access

3. Reload Configuration: Command Syntax:/showcase-manage reload

4. Restart if Needed: Some settings require server restart:

   • Database settings
   • Item icon configuration
   • Language changes

Invalid Configuration Values

Example Valid Configuration:

# ✅ Correct format
shares:
  item:
    enabled: true
    defaultDuration: 30
    maxDuration: 60

# ❌ Common mistakes
shares:
item:  # Missing indentation
  enabled: yes  # Use 'true' instead
  defaultDuration: -10  # Negative value

Share Creation Issues

Shares Not Creating

Debugging Steps:

1. Check Item in Hand:

   Must be holding an item for /showcase item
   Empty hand = no share created

2. Verify Cooldowns:

   shares:
     item:
       cooldown: 5  # seconds between shares

3. Check Share Limits:

   general:
     maxSharesPerPlayer: 10  # Max active shares

4. Review Expiration:

   shares:
     item:
       defaultDuration: 30  # minutes

Container Sharing Problems

Requirements for Container Sharing:

1. Open Container First:

   • Open chest/barrel within 10 seconds
   • Don't close the container too quickly

2. Check Detection Timeout:

   shares:
     container:
       detectionTimeout: 10  # seconds

3. Supported Containers:

   • ✅ Chests (single/double)
   • ✅ Barrels
   • ✅ Shulker boxes
   • ✅ Dispensers/Droppers
   • ❌ Player inventories
   • ❌ Crafting tables

Performance Issues

Server Lag

Optimization Steps:

1. Adjust Cache Settings:

   performance:
     cacheSize: 2000  # Increase for more players
     cacheExpiration: 180  # Reduce for less memory usage

2. Reduce Share Durations:

   shares:
     item:
       defaultDuration: 15  # Shorter duration
       maxDuration: 30

3. Increase Cleanup Frequency:

   general:
     cleanupInterval: 2  # Clean expired shares more often

4. Disable Detailed Stats:

   performance:
     collectDetailedStats: false  # Reduces processing

Memory Usage

Monitor Memory Usage:

# Check JVM memory
jps -v | grep minecraft

# Monitor share count
/showcase-manage list

Memory Optimization:

performance:
  cacheSize: 500  # Reduce for less RAM usage
  databaseCleanup: true  # Enable auto-cleanup
  compactInterval: 30  # More frequent compaction

Search and Display Issues

GUI Not Opening

Solutions:

1. Check Share ID:

   # Get valid share IDs
   /showcase-manage list

2. Verify Share Exists:

   Share may have expired or been cancelled
   Check expiration time

3. Test with Different Share:

   # Create test share
   /showcase item
   # Note the ID and try viewing immediately

Statistics Not Displaying

Debugging:

1. Check Statistics Collection:

   performance:
     collectDetailedStats: true
     statsUpdateInterval: 30

2. Verify Player Data:

   New players may have limited statistics
   Play for a while to generate data

3. Enable Debug Logging:

   debug:
     enabled: true
     logLevel: "DEBUG"

Mod Compatibility

Conflicting Mods

Testing Compatibility:

1. Isolate Showcase:

   Test with only Showcase + dependencies
   Add other mods one by one

2. Check for Errors:

   grep -i "showcase\|error" logs/latest.log

3. Report Conflicts: Include mod list when reporting issues

Version Mismatches

Ensure All Components Match:

Minecraft 1.21.6:
├── Fabric Loader 0.16.0+
├── Fabric API 0.110.0+
└── Showcase 2.3.1+mc1.21.6

❌ Don't mix versions:
Showcase 2.3.1+mc1.21.4 on MC 1.21.6 server

Getting Help

Log Collection

Essential Information for Support:

1. Server Information:

   # Minecraft version
   cat server.properties | grep level-name
   
   # Mod versions
   /mods | grep -E "(showcase|fabric)"

2. Error Logs:

   # Recent errors
   tail -100 logs/latest.log | grep -i error
   
   # Showcase-specific logs
   grep -i showcase logs/latest.log

3. Configuration:

   # Include your config (remove sensitive data)
   cat config/showcase/config.yml

Debug Mode

Enable Full Debugging:

debug:
  enabled: true
  logLevel: "DEBUG"
  logCommands: true
  logPermissions: true
  logChatKeywords: true

Understanding Debug Output:

[DEBUG] [Showcase] Permission check: player=Steve, permission=showcase.command.item, result=true
[DEBUG] [Showcase] Share created: id=abc123, type=ITEM, duration=PT30M
[DEBUG] [Showcase] Chat keyword processed: [item] -> [Diamond Sword]

Support Channels

Before Reporting Issues

Checklist:

• Updated to latest Showcase version
• Checked this troubleshooting guide
• Tested with minimal mod setup
• Collected relevant logs and config
• Searched existing GitHub issues

Information to Include:

1. Exact error message or behavior
2. Steps to reproduce the issue
3. Server/client versions and mod list
4. Relevant configuration sections
5. Log excerpts (no full logs unless requested)

Related Topics

• Configuration File - Complete configuration reference
• Permissions - Permission setup guide
• FAQ - Frequently asked questions
• Installation - Installation guide