Troubleshooting

This guide covers common issues you might encounter with McDis-RCON and their solutions.

Installation & Setup Issues

McDis-RCON won't start

Symptoms:

Error when running mcdis run
Python crashes or shows import errors

Possible causes:

Missing dependencies
Invalid md_config.yml
Wrong Python version

Solutions:Check Python version:

python --version  # Should be 3.8+

Reinstall dependencies:

pip install mcdis-rcon --upgrade

Validate configuration:

# Regenerate config
mcdis init
# Compare with your custom config

Check for error messages:

mcdis run 2>&1 | tee mcdis_error.log

Bot doesn't connect to Discord

Symptoms:

“Error while running discord client” message
Bot shows offline in Discord

Possible causes:

Invalid bot token
Bot not invited to server
Network/firewall issues

Solutions:Verify bot token:

md_config.yml

Bot Token: "YOUR_ACTUAL_TOKEN_HERE"
# No quotes inside the token itself

Check bot invite:

Go to Discord Developer Portal
Select your application
OAuth2 → URL Generator
Select bot scope
Select Administrator permissions
Use generated URL to invite bot

Test network:

ping discord.com
curl https://discord.com/api/v10/gateway

Panel channel not found

Error message: Error: Channel with id XXXXX not found.Causes:

Wrong channel ID in config
Bot doesn’t have channel access
Channel was deleted

Solutions:Get correct channel ID:

Enable Developer Mode in Discord (Settings → Advanced)
Right-click the channel → Copy ID

Update md_config.yml:

Panel ID: 1234567890  # Your channel ID (no quotes)

Check bot permissions:

Bot needs Read/Send Messages in the channel
Grant Administrator role for simplicity

Verify channel exists:

Ensure the channel hasn’t been deleted
Create a new channel if needed

Process Management Issues

Server won't start

Symptoms:

!!start SMP shows “Initializing” but nothing happens
Console thread shows “[Initializing Process…]”
Process immediately stops

Possible causes:

Incorrect start_cmd
Missing server files
Port already in use
Insufficient memory

Solutions:Test start command manually:

cd McDis/SMP
java -Xmx4G -jar server.jar nogui
# Does it work?

Check for required files:

ls McDis/SMP/
# Should see server.jar (or equivalent)

Check port availability:

# Linux/Mac
netstat -tuln | grep 25565

# Windows
netstat -ano | findstr 25565

Verify memory:

free -h  # Linux
# Ensure enough RAM available

Check error reports:

Look in “Error Reports” Discord thread
Check terminal output

Server won't stop gracefully

Symptoms:

!!stop SMP doesn’t stop the server
Process runs for 60 seconds then force-kills

Causes:

Incorrect stop_cmd
Server not responding to stop command
Plugin preventing shutdown

Solutions:Verify stop command:

md_config.yml

Processes:
  Servers:
    SMP:
      stop_cmd: "stop"  # Most servers
      # OR
      stop_cmd: "end"   # Velocity/BungeeCord

Try manual stop:

Go to Console SMP thread
Type stop directly
Does it work?

Use kill if stuck:

!!kill SMP  # Force terminate

Check plugins:

Some plugins intercept shutdown
Disable problematic plugins

Processes keep crashing

Symptoms:

Server starts then immediately stops
Console shows crash errors
Repeated restart loops

Debugging steps:Check console output:

Read the Console thread for errors
Look for Java exceptions
Note any “FATAL” or “ERROR” messages

Common crash causes:

Out of memory:

java.lang.OutOfMemoryError: Java heap space

Solution: Increase -Xmx value

Corrupted world:
```
Exception reading world data
```
Solution: Restore from backup
Plugin conflicts:
```
Error loading plugin XYZ
```
Solution: Remove/update the plugin
Wrong Java version:
```
Unsupported class file major version
```
Solution: Install correct Java version

Test in safe mode:

Rename plugins/ to plugins.backup/
Start server
If it works, add plugins back one by one

Plugin & Addon Issues

Plugins not loading

Symptoms:

!!mdreload SMP completes but plugin doesn’t work
No “Plugin imported” message

Checklist:Verify file location:

McDis/SMP/.mdplugins/your_plugin.py  ✓
McDis/.mdaddons/your_plugin.py       ✗ (wrong location)

Check class name:

# Correct
class mdplugin:
    def __init__(self, client):

# Wrong
class MyPlugin:  # Should be 'mdplugin'

Check for syntax errors:

python -m py_compile McDis/SMP/.mdplugins/your_plugin.py

Look for import errors:

Check Error Reports thread
Terminal may show import failures

Process must be running:

!!start SMP      # Start first
!!mdreload SMP   # Then reload

Addons not working

Symptoms:

!!adreload runs but addon doesn’t respond
No events being triggered

Differences from plugins:Class name:

# Addons use 'mdaddon'
class mdaddon:  # Not 'mdplugin'
    def __init__(self, client):

Event names:

# Addons: no 'listener_' prefix
async def on_message(self, message):  # Correct

# Plugins: with 'listener_' prefix
async def listener_on_message(self, message):  # For plugins

File location:

McDis/.mdaddons/your_addon.py  ✓

Folder-based addons:

McDis/.mdaddons/my_addon/
├── __init__.py  ← Must contain 'mdaddon' class
└── helpers.py

Reload:

!!adreload  # No process name needed

Plugin errors in Error Reports

What to check:

Read the traceback:
- Error Reports thread shows full stack trace
- Look for line numbers
- Identify which function failed

Common errors: AttributeError:

AttributeError: 'NoneType' object has no attribute 'id'

Cause: Accessing object that doesn’t exist
Fix: Add null checks

if self.client.panel:
    await self.client.panel.send("message")

TypeError:

TypeError: object str can't be used in 'await' expression

Cause: Missing async/await
Fix: Make function async

async def listener_on_message(self, message):
    await message.channel.send("Hello")

ImportError:

ImportError: No module named 'requests'

Cause: Missing dependency
Fix: Install the module

pip install requests

Debug with print statements:

def listener_events(self, log: str):
    print(f"DEBUG: Received log: {log}")
    # Your code here

File Manager Issues

File Manager not showing files

Symptoms:

Dropdown is empty
Can’t navigate folders

Solutions:Click reload:

Press 🔄 button

Check path:

Use 📌 to navigate to a known path
Ensure you’re in a valid McDis folder

Over 25 files:

Dropdown only shows first 25 items
Use Terminal for folders with many files

Permissions:

Ensure McDis-RCON can read the folder
Check file permissions on Linux

Can't upload files

Symptoms:

Uploader enabled but files not saving
“Saving files…” message but nothing happens

Checklist:Uploader status:

Tools → Uploader → Status: Run

Valid path:

Path must start with McDis/
Path must exist
Example: McDis/SMP/plugins

File permissions:

# Linux - check write permissions
ls -la McDis/SMP/plugins
# Should show write permissions for user

Discord upload limit:

Files must be under Discord’s upload limit (8MB for free, 100MB for Nitro)
For larger files, use File Manager upload or manual methods

Overwrite mode:

If file exists and overwrite is disabled, upload is skipped
Enable overwrite or rename file

Can't download large files

Problem: Files over 5MB won’t downloadSolution: Use Flask integration

Enable Flask

md_config.yml

Flask:
  Allow: true
  IP: "your_public_ip"
  Port: 5000

Start Flask server

Tools → Flask → Run

Request file

File Manager → Select file → Request

Use download link

Click the generated HTTP link

See Flask Integration for details.

Backup Issues

Backup creation fails

Symptoms:

“Create backup” option doesn’t work
Backup process hangs

Common causes:Process still running:

Backups require the process to be stopped

Solution:

!!stop SMP
# Wait for full stop
# Then create backup

Insufficient disk space:

df -h  # Check available space

Backups compress but still need space
Free up disk space if needed

Large world size:

Very large worlds (10GB+) take time to compress
Be patient, check progress in terminal

File permissions:

ls -la McDis/.mdbackups/
# Ensure write permissions

Can't restore from backup

Steps to restore:

Stop the server

!!stop SMP

Download backup

Navigate to .mdbackups/SMP/ and request the backup file

Clear server folder

# Backup current state first!
mv McDis/SMP McDis/SMP.old
mkdir McDis/SMP

Extract backup

unzip "SMP 1.zip" -d McDis/SMP/

Remove backup log

rm McDis/SMP/backup_log.txt

Start server

!!start SMP

Performance Issues

High memory usage

Symptoms:

Server sluggish
System running out of RAM

Check memory usage:

Tools → Processes → Check RAM per process

Solutions:Adjust JVM flags:

md_config.yml

start_cmd: "java -Xmx4G -Xms4G -jar server.jar nogui"
# -Xms = initial heap
# -Xmx = maximum heap

Optimize JVM:

start_cmd: "java -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -jar server.jar nogui"

Reduce view distance:

server.properties

view-distance=8  # Lower = less RAM

Remove unused plugins:

Disable plugins you don’t need

Console lag / delayed messages

Symptoms:

Console messages appear slowly in Discord
Backlog of messages

Causes:

Server producing logs faster than Discord can send
McDis-RCON queues messages

Solutions:Use blacklist:

md_config.yml

blacklist:
  - "[debug]"
  - "[FML]"
  - "Can't keep up!"
# Filter verbose logs

Reduce server verbosity:

Configure server logging levels
Disable debug plugins

Restart McDis-RCON:

Clears message queue
Resets relay

Discord Integration Issues

Bot not responding to commands

Symptoms:

!!start SMP does nothing
Commands don’t work

Checklist:Correct channel:

Commands only work in the panel channel
Or in process console threads

Correct prefix:

Discord: !!start SMP (with !!)
Console thread: start (no prefix)

Command format:

# Correct
!!start SMP
!!start-all

# Wrong
!!start smp  # Actually, case-insensitive, this works
!! start SMP  # Space after prefix - won't work
start SMP     # Missing prefix in panel channel

Bot permissions:

Ensure bot can read messages
Grant Administrator for simplicity

Error Reports thread missing

Problem: Can’t find “Error Reports” threadSolutions:Check thread list:

Click “Threads” in Discord
Look for archived threads

Thread auto-created:

McDis-RCON creates it automatically
Should appear when first error occurs

Recreate:

Restart McDis-RCON
Threads are recreated on startup

Getting Help

If you can’t resolve your issue:

Gather information

McDis-RCON version: pip show mcdis-rcon
Python version: python --version
Operating system
Error messages from:
- Terminal output
- Error Reports thread
- Console threads

Check existing issues

Visit the GitHub Issues page to see if your problem is already reported

Create a bug report

If no existing issue, create a new one with:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Error messages/logs
Configuration (remove sensitive data like bot tokens)

Never share your bot token publicly. Remove it from logs and config files before posting.

Useful Commands for Debugging

# Check McDis-RCON version
pip show mcdis-rcon

# Check Python version
python --version

# Validate md_config.yml syntax
python -c "import yaml; yaml.safe_load(open('md_config.yml'))"

# Check running processes
ps aux | grep java

# Check port usage
netstat -tuln | grep 25565

# Check disk space
df -h

# Check memory usage
free -h

# View McDis-RCON logs
tail -f mcdis.log  # If logging to file

# Test Discord API connectivity
curl https://discord.com/api/v10/gateway

Common Error Messages

Error	Meaning	Solution
`KeyError: 'Bot Token'`	Missing config key	Regenerate config with `mcdis init`
`discord.errors.LoginFailure`	Invalid bot token	Check token in Discord Developer Portal
`Channel with id X not found`	Wrong channel ID	Update Panel ID in config
`Address already in use`	Port conflict	Change port or stop conflicting service
`Permission denied`	Insufficient permissions	Check file/folder permissions
`Module not found`	Missing dependency	Run `pip install mcdis-rcon`

For more detailed troubleshooting, enable debug logging in your plugins/addons with print() statements.

Panel Management

Extending McDis-RCON

Advanced Usage

Installation & Setup Issues

Process Management Issues

Plugin & Addon Issues

File Manager Issues

Backup Issues

Performance Issues

Discord Integration Issues

Getting Help

Useful Commands for Debugging

Common Error Messages

Build docs developers (and LLMs) love

Panel Management

Extending McDis-RCON

Advanced Usage

​Installation & Setup Issues

​Process Management Issues

​Plugin & Addon Issues

​File Manager Issues

​Backup Issues

​Performance Issues

​Discord Integration Issues

​Getting Help

​Useful Commands for Debugging

​Common Error Messages

Build docs developers (and LLMs) love

Installation & Setup Issues

Process Management Issues

Plugin & Addon Issues

File Manager Issues

Backup Issues

Performance Issues

Discord Integration Issues

Getting Help

Useful Commands for Debugging

Common Error Messages