Troubleshooting

This guide covers common issues encountered when running PocketMine-MP servers and their solutions.

Server Won’t Start

PHP version mismatch

Symptoms:

“PHP version not supported” error
Server immediately exits
“Syntax error” in core files

Solution:PocketMine-MP requires specific PHP versions. Check requirements:

# Check PHP version
php -v

# Install correct PHP version
# See installation docs for version requirements

Each PocketMine-MP version requires a specific PHP version. Check the release notes or README.

Port already in use

Symptoms:

“Failed to bind to port” error
“Address already in use”

Solution:

Linux/macOS
Windows

# Find process using port 19132
sudo lsof -i :19132

# Kill the process
sudo kill -9 <PID>

# Or change port in server.properties
server-port=19133

# Find process using port
netstat -ano | findstr :19132

# Kill process
taskkill /PID <PID> /F

# Or change port in server.properties

Missing PHP extensions

Symptoms:

“Extension X is not loaded” error
Fatal PHP errors on startup

Solution:Install required PHP extensions:

# Linux (example for Ubuntu)
sudo apt-get install php-pthreads php-yaml php-sqlite3 php-zip

# Check installed extensions
php -m

PocketMine-MP requires: pthreads, yaml, sqlite3, zlib, curl, and others. Use the official installation script for automatic setup.

Permission denied errors

Symptoms:

“Permission denied” when accessing files
Cannot write to directories

Solution:

# Fix ownership
sudo chown -R $(whoami) /path/to/server

# Fix permissions
chmod -R 755 /path/to/server
chmod 644 server.properties pocketmine.yml

Memory limit too low

Symptoms:

“Memory limit exceeded” error
Server exits during startup

Solution:Increase memory limit in pocketmine.yml:

memory:
  main-hard-limit: 2048  # Increase to 2GB

Or increase PHP memory limit:

# Edit php.ini
memory_limit = 2048M

Connection Issues

Players can't connect

Symptoms:

“Unable to connect to world” error
Connection timeout
Server not visible in LAN games

Troubleshooting steps:

Verify server is running

# Check if server is listening
netstat -an | grep 19132

Check firewall

# Linux
sudo ufw status
sudo ufw allow 19132/udp

# Windows - check Windows Defender Firewall

Verify port forwarding (if behind router)

Forward UDP port 19132 to server IP
Check router configuration
Test with port checker tool

Check IP configuration

server.properties

# Leave empty for automatic
server-ip=

# Or set to specific interface
server-ip=0.0.0.0

Verify client compatibility

Ensure client Minecraft version matches server version

Frequent disconnections

Symptoms:

Players randomly disconnect
“Connection lost” messages
“Timed out” errors

Solutions:

Check server performance:

# Monitor TPS
status

# Target: TPS ~20
# If TPS < 19, optimize server performance

Adjust network settings:

pocketmine.yml

network:
  # Increase if on poor networks
  batch-threshold: 512
  
  # Decrease compression level
  compression-level: 4

Check for packet loss:

Test network quality
Check player internet connection
Consider using better hosting

Xbox auth failures

Symptoms:

“Failed to authenticate with Xbox Live”
“Could not verify account”

Solutions:

Verify server configuration:

server.properties

xbox-auth=true

Check Xbox Live service status:

Visit Xbox Live status page
Wait for service restoration

Player must be signed into Xbox:

Player needs Xbox Live account
Must be signed in on device

Check encryption:

pocketmine.yml

network:
  enable-encryption: true

Performance Issues

Low TPS / Server lag

Symptoms:

TPS below 19
Delayed block updates
Slow player movement

Diagnosis:

# Enable timings
timings on

# Wait 5-10 minutes

# Generate report
timings paste

Common causes and solutions:

Heavy plugins

Identify laggy plugins in timings
Disable or replace problem plugins
Contact plugin developers

Too many entities

Reduce mob spawn rates
Clear entities: clear @e[type=!player]
Use entity limiting plugins

Large view distance

view-distance=6  # Reduce from 12

Expensive chunk operations

chunk-ticking:
  tick-radius: 2  # Reduce from 3
  blocks-per-subchunk-per-tick: 2

High memory usage

Symptoms:

Memory warnings in console
“Low memory” messages
Out of memory crashes

Solutions:

Enable memory management:

pocketmine.yml

memory:
  main-limit: 768  # Enable soft limit
  main-hard-limit: 1024
  check-rate: 20
  continuous-trigger: true

Reduce memory usage:

server.properties

view-distance=6  # Lower view distance

pocketmine.yml

chunk-sending:
  per-tick: 3  # Reduce chunk loading speed

memory:
  max-chunks:
    chunk-radius: 4  # Limit during low memory

Check for memory leaks:

# Generate memory dump
dump memory

# Review plugins for leaks
# Remove problematic plugins

Increase server RAM:

Upgrade hosting plan
Increase allocated memory

High CPU usage

Symptoms:

CPU at 100%
System sluggishness
Slow server response

Solutions:

Check timings report for CPU-intensive operations
Optimize world generation:

settings:
  async-workers: 4  # Match CPU cores

chunk-generation:
  population-queue-size: 16  # Reduce

Reduce compression:

network:
  compression-level: 4  # Lower level
  async-compression: true  # Offload to workers

Pre-generate worlds:

Use world generation plugins
Generate chunks before players join

World Issues

World not loading

Symptoms:

“World not found” error
Server starts but world missing
Players spawn in void

Solutions:

Check world directory:

ls -la worlds/

# Ensure world folder exists
# Check folder name matches server.properties

Verify configuration:

server.properties

level-name=world  # Must match folder name

Check world format:

pocketmine.yml

level-settings:
  default-format: leveldb  # Or mcregion

Restore from backup:

# Copy backup to worlds directory
cp -r backup/world worlds/

World corruption

Symptoms:

Chunks not loading
“Failed to read chunk” errors
Visual glitches
Server crashes when loading specific areas

Solutions:

Stop server immediately to prevent further corruption
Backup current state:

cp -r worlds/world worlds/world.backup

Try automatic repair:

# Start server, corruption may auto-fix
# Check console for errors

Manual region deletion:

# Delete corrupted regions (LAST RESORT)
# This deletes chunks permanently
rm worlds/world/region/corrupted_file

Restore from backup:

rm -rf worlds/world
cp -r backup/world worlds/

Always maintain regular backups to recover from corruption.

Cannot generate chunks

Symptoms:

Players fall through world
Chunks appear as void
“Chunk generation failed” errors

Solutions:

Check generator settings:

server.properties

level-type=DEFAULT  # Or FLAT, VOID
generator-settings=  # Leave empty for default

Verify async workers:

pocketmine.yml

settings:
  async-workers: auto  # Or 2+

Check disk space:

df -h  # Ensure sufficient space

Check permissions:

chmod -R 755 worlds/

Plugin Issues

Plugin won't load

Symptoms:

Plugin not in plugins list
“Failed to load plugin” error
API version mismatch

Solutions:

Check API compatibility:

# Server API version
version

# Plugin must support this API version

Verify file integrity:

Ensure .phar file is complete
Re-download plugin
Check file permissions

Check dependencies:

Install required dependencies
Check plugin documentation

Review console errors:

# Look for specific error messages
tail -f server.log

Plugin crashes server

Symptoms:

Server crashes when plugin loads
Segmentation fault
Fatal PHP errors

Solutions:

Remove problematic plugin:

mv plugins/ProblemPlugin.phar plugins/disabled/

Update plugin:

Check for updates on Poggit
Download latest version

Report bug:

Contact plugin developer
Provide crash report
Include server version and logs

Use alternative plugin:

Find replacement on Poggit
Test alternatives

Plugin conflicts

Symptoms:

Features not working
Unexpected behavior
Errors mentioning multiple plugins

Solutions:

Test plugins individually:

# Disable all plugins
mv plugins/*.phar plugins/disabled/

# Enable one at a time
mv plugins/disabled/Plugin1.phar plugins/

Check for conflicts:

Review plugin documentation
Look for known conflicts
Contact developers

Adjust plugin priorities:

Some plugins support load order
Check plugin.yml settings

Crash Issues

Understanding crash reports

Location: crashdumps/ directoryKey information:

Error message: What went wrong
Stack trace: Where it happened
Plugin list: Active plugins
Server version: PocketMine-MP version

Automatic reporting:

pocketmine.yml

auto-report:
  enabled: true  # Sends crash reports to PMMP team
  send-code: true
  send-settings: true

Recurring crashes

Steps to diagnose:

Review crash dumps

Check crashdumps/ for patterns

Disable plugins

Test with plugins disabled

Update server

Ensure running latest stable version

Check resources

Monitor RAM, CPU, disk space

Review timings

Identify performance bottlenecks

Report bug

If PocketMine-MP bug, report to GitHub Security (if security-related) or Issues

Out of memory crashes

Solutions:

Increase memory limit:

pocketmine.yml

memory:
  main-hard-limit: 2048  # Increase

Enable memory management:

memory:
  main-limit: 1536  # Enable soft limit
  continuous-trigger: true

Reduce memory usage:

Lower view distance
Remove heavy plugins
Reduce player count
Clear entities regularly

Upgrade hosting:

Get more RAM
Use dedicated server

Getting Help

If you can’t resolve your issue:

Discord

Join the official PocketMine-MP Discord server for community support

Stack Overflow

Ask questions tagged with pocketmine on Stack Overflow

GitHub Issues

Report bugs on GitHub (not for support questions)

Documentation

Read the official PocketMine-MP documentation

Information to Provide

When asking for help, include:

Server version

version
# Output: This server is running PocketMine-MP version ...

PHP version

php -v

Operating system

Linux distribution and version
Windows version
macOS version

Error messages

Copy exact error messages from console

Crash dumps

Upload relevant crash dump files

Plugin list

plugins

Configuration

Relevant parts of server.properties or pocketmine.yml

Steps to reproduce

Exactly how to trigger the issue

Do not share sensitive information:

ops.txt contents
API keys or passwords
Player data
Full server IP addresses

Next Steps

Performance

Optimize server performance

Configuration

Review configuration options

Get Started

Core Concepts

Plugin Development

Server Administration

Server Won’t Start

Connection Issues

Performance Issues

Heavy plugins

Too many entities

Large view distance

Expensive chunk operations

World Issues

Plugin Issues

Crash Issues

Getting Help

Discord

Stack Overflow

GitHub Issues

Documentation

Information to Provide

Next Steps

Performance

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Plugin Development

Server Administration

​Server Won’t Start

​Connection Issues

​Performance Issues

Heavy plugins

Too many entities

Large view distance

Expensive chunk operations

​World Issues

​Plugin Issues

​Crash Issues

​Getting Help

Discord

Stack Overflow

GitHub Issues

Documentation

​Information to Provide

​Next Steps

Performance

Configuration

Build docs developers (and LLMs) love

Server Won’t Start

Connection Issues

Performance Issues

World Issues

Plugin Issues

Crash Issues

Getting Help

Information to Provide

Next Steps