Troubleshooting Guide

This guide covers common issues administrators encounter and provides step-by-step solutions for troubleshooting L2J Mobius Chronicle 4 servers.

Server Startup Issues

Server fails to start - Database connection error

Symptoms:

Server crashes during startup
Error: “Cannot connect to database”
Connection timeout errors

Solutions:

Verify database is running:

systemctl status mysql
# or
systemctl status mariadb

Check database credentials in dist/game/config/Database.ini:

Driver = com.mysql.jdbc.Driver
URL = jdbc:mysql://localhost/l2jmobius
Login = root
Password = your_password

Test database connection:

mysql -u root -p -e "SHOW DATABASES;"

Verify database exists:

SHOW DATABASES LIKE 'l2jmobius';

Check firewall rules:

sudo ufw allow 3306/tcp

Ensure database user has proper permissions on the L2J database.

OutOfMemoryError during startup

Symptoms:

java.lang.OutOfMemoryError: Java heap space
Server crashes while loading data

Solutions:

Increase JVM heap size:

java -Xms2G -Xmx4G -jar L2J_Mobius_C4_ScionsOfDestiny.jar

For larger servers, allocate more memory:

java -Xms4G -Xmx8G -XX:+UseG1GC -jar L2J_Mobius_C4_ScionsOfDestiny.jar

Monitor memory usage:

//serverinfo

Check for memory leaks:

Review dist/game/log/error.log
Look for repetitive object creation
Consider profiling with VisualVM

Port already in use

Symptoms:

java.net.BindException: Address already in use
Cannot bind to port 7777 or 9014

Solutions:

Check what’s using the port:

sudo netstat -tulpn | grep :7777
sudo lsof -i :7777

Kill the process:

sudo kill -9 <PID>

Change server ports in dist/game/config/Network.ini:

GameServerPort = 7777
LoginServerPort = 9014

Wait for port to be released:

# Ports may remain in TIME_WAIT state for up to 2 minutes
watch -n 1 'netstat -an | grep :7777'

Admin Command Issues

Admin commands not working

Symptoms:

Commands return “You don’t have the access rights to use this command”
Commands not recognized

Solutions:

Verify access level:

SELECT char_name, accesslevel FROM characters WHERE char_name = 'YourGMName';

Set access level in database:

UPDATE characters SET accesslevel = 70 WHERE char_name = 'YourGMName';

Reload character or relog
Check dist/game/config/AccessLevels.xml:

<access level="70" name="Admin" isGM="true" .../>

Verify command exists in dist/game/config/AdminCommands.xml:

<command name="admin_teleport" accessLevel="30" />

Check admin command handler is loaded:

//reload handler

Source: See Access Levels

Reload command warnings

Symptoms:

“WARNING: There are several known issues regarding this feature”
Server instability after reload

Understanding the Issue:Reloading server data at runtime can cause:

Memory leaks
Inconsistent game state
Player disconnections
Cache corruption

Best Practices:

Never use //reload commands on live production servers.

Safe reload operations (development only):

//reload html - Generally safe
//reload config - Use with caution
//reload quest <id> - Safe for single quest

Unsafe reload operations:

//reload npc - Can cause spawn issues
//reload skill - May break active buffs
//reload item - Can corrupt inventories

Alternative: Restart server during low-traffic periods.Source: handlers/admincommandhandlers/AdminReload.java:260

Player Connection Issues

Players cannot connect to server

Symptoms:

“Server is currently unavailable”
Timeout during connection
Connection refused errors

Solutions:

Verify server is running:

ps aux | grep L2J
netstat -tulpn | grep 7777

Check firewall rules:

sudo ufw status
sudo ufw allow 7777/tcp
sudo ufw allow 9014/tcp

Verify external IP configuration:

In dist/game/config/Network.ini:

ExternalHostname = your.public.ip.address
InternalHostname = 127.0.0.1

Test port accessibility:

telnet your.server.ip 7777

Check NAT/port forwarding:

Forward port 7777 (game server)
Forward port 9014 (login server)

Review connection logs:

tail -f dist/game/log/java.log | grep "Connection"

Players getting kicked frequently

Symptoms:

Random disconnections
“Connection lost” errors
Timeout messages

Solutions:

Check flood protector settings in dist/game/config/FloodProtector.ini:

# May be too aggressive
PacketFloodProtector = True
PacketInterval = 100
PacketMaxAttempts = 10

Increase client timeout in dist/game/config/Network.ini:

ClientPacketQueueSize = 20
ClientPacketQueueMaxPacketsPerSecond = 80
ClientPacketQueueMeasureInterval = 5

Monitor server performance:

//serverinfo

Check for network issues:

ping -c 100 your.server.ip

Review error logs:

grep -i "disconnect" dist/game/log/java.log

Performance Issues

Server lag and poor performance

Symptoms:

High latency
Delayed commands
Slow NPC responses

Diagnostic Steps:

Check server metrics:

//serverinfo

Monitor memory usage:

Used memory > 80% of max: Increase heap
Frequent GC: Optimize or add memory

Check thread count:

1000 threads: Possible thread leak
Investigate recent changes

Review CPU usage:

top -p $(pgrep -f L2J)

Solutions:

Optimize JVM settings:

java -Xms4G -Xmx8G \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+DisableExplicitGC \
  -XX:+ParallelRefProcEnabled \
  -jar L2J_Mobius_C4_ScionsOfDestiny.jar

Reduce geodata precision in dist/game/config/GeoEngine.ini:

# Lower value = better performance, less accuracy
PathFinding = 1

Limit active spawns:

Review spawn density
Disable unnecessary NPCs

Database optimization:

OPTIMIZE TABLE characters;
OPTIMIZE TABLE items;
ANALYZE TABLE characters;

Enable database connection pooling in dist/game/config/Database.ini:

MaximumPoolSize = 10
MinimumIdle = 5

Memory leaks

Symptoms:

Memory usage continuously increasing
Server crashes after extended runtime
OutOfMemoryError in logs

Diagnostic:

Monitor memory over time:

watch -n 60 '//serverinfo'

Take heap dump:

jmap -dump:live,format=b,file=heap.bin <PID>

Analyze with VisualVM or Eclipse MAT

Common Causes:

Improper use of //reload commands
Custom scripts not cleaning up
Event handlers not deregistered
Static collections growing unbounded

Solutions:

Restart server regularly:

//server_restart 300

Avoid runtime reloads on production
Review custom scripts for cleanup
Increase heap if memory is legitimately needed

Data and Database Issues

Character data corruption

Symptoms:

Character cannot login
Missing items or skills
Stuck at invalid coordinates

Solutions:

Use repair command:

//repairchar <character_name>

Reset character position:

UPDATE characters 
SET x=83400, y=147943, z=-3404 
WHERE char_name='StuckPlayer';

Restore from backup:

mysql -u root -p l2jmobius < backup_YYYYMMDD.sql

Clear invalid items:

DELETE FROM items WHERE item_id NOT IN (SELECT item_id FROM item_templates);

Always backup database before making manual changes.

Quest not working

Symptoms:

Quest won’t start
NPCs not responding
Quest progression blocked

Solutions:

Reload specific quest:

//reload quest <quest_id>
# or
//reload quest <quest_name>

Check quest state:

SELECT * FROM character_quests WHERE char_id = <char_id>;

Reset quest for player:

DELETE FROM character_quests 
WHERE char_id = <char_id> AND quest_name = 'Q00255_Tutorial';

Verify quest script exists:

ls dist/game/data/scripts/quests/Q00255_Tutorial/

Check script errors in logs:

grep -i "quest" dist/game/log/error.log

Spawn and NPC Issues

NPCs not spawning

Symptoms:

Missing NPCs in world
Empty towns or hunting grounds

Solutions:

Respawn all NPCs:

//respawnall

Check spawn data loaded:

grep -i "spawn" dist/game/log/java.log

Manually spawn NPC:

//spawn <npc_id>

Verify NPC template exists:

//reload npc

Check spawn tables:

SELECT * FROM spawnlist WHERE npc_id = 30001;

Raid boss not respawning

Symptoms:

Raid boss killed but not respawning
Incorrect respawn time

Solutions:

Check raid boss status:

SELECT * FROM grandboss_data WHERE boss_id = <boss_id>;
SELECT * FROM raidboss_spawnlist WHERE boss_id = <boss_id>;

Reset respawn timer:

UPDATE grandboss_data 
SET respawn_time = 0 
WHERE boss_id = <boss_id>;

Force respawn:

//grandboss <boss_id>

Reload boss manager:

//reload handler

Olympiad and Siege Issues

Olympiad stuck or not cycling

Symptoms:

Olympiad period not ending
Heroes not being selected

Solutions:

Check Olympiad status:

//checkolympiad

Manually save Olympiad:

//saveolymp

Force end period and select heroes:

//endolympiad

//endolympiad immediately cycles the Olympiad. Use only when period is truly stuck.

Check Olympiad configuration in dist/game/config/Olympiad.ini:

AltOlyPeriod = 2592000000
AltOlyWeeklyPeriod = 604800000

Logging and Debugging

Enable Debug Logging

For development troubleshooting, enable verbose logging:

Locate logging configuration (typically in startup scripts)
Enable debug mode:

java -Ddebug=true -jar L2J_Mobius_C4_ScionsOfDestiny.jar

Review logs:

tail -f dist/game/log/java.log
tail -f dist/game/log/error.log

Common Log Locations

dist/game/log/
├── java.log          # General server log
├── error.log         # Error messages
├── chat.log          # Chat messages
├── items.log         # Item transactions
└── audit.log         # GM actions

Emergency Procedures

Server Crash Recovery

Stop any running instances:
```
pkill -f L2J
```

Check database integrity:

mysqlcheck -u root -p --auto-repair l2jmobius

Review crash logs:
```
less dist/game/log/error.log
```

Restore from backup if needed:

mysql -u root -p l2jmobius < backup.sql

Start server with increased logging:

java -Xmx4G -jar L2J_Mobius_C4_ScionsOfDestiny.jar > startup.log 2>&1

Getting Help

Server Logs

Always include relevant log excerpts when requesting help

L2J Forums

Official community support

GitHub Issues

Report bugs and issues

Discord Community

Real-time community assistance

Prevention Best Practices

Regular Backups: Automate daily database backups
Staging Environment: Test changes before production
Monitor Resources: Set up alerting for memory/CPU
Update Regularly: Keep server updated with patches
Document Changes: Maintain changelog of modifications
Limit Access: Restrict admin permissions appropriately

Admin Commands

Command reference

Security

Access control

Monitoring

Performance monitoring

Get Started

Server Setup

Game Systems

Scripting

Administration

Server Startup Issues

Admin Command Issues

Player Connection Issues

Performance Issues

Data and Database Issues

Spawn and NPC Issues

Olympiad and Siege Issues

Logging and Debugging

Enable Debug Logging

Common Log Locations

Emergency Procedures

Getting Help

Server Logs

L2J Forums

GitHub Issues

Discord Community

Prevention Best Practices

Admin Commands

Security

Monitoring

Build docs developers (and LLMs) love

Get Started

Server Setup

Game Systems

Scripting

Administration

​Server Startup Issues

​Admin Command Issues

​Player Connection Issues

​Performance Issues

​Data and Database Issues

​Spawn and NPC Issues

​Olympiad and Siege Issues

​Logging and Debugging

​Enable Debug Logging

​Common Log Locations

​Emergency Procedures

​Getting Help

Server Logs

L2J Forums

GitHub Issues

Discord Community

​Prevention Best Practices

​Related Documentation

Admin Commands

Security

Monitoring

Build docs developers (and LLMs) love

Server Startup Issues

Admin Command Issues

Player Connection Issues

Performance Issues

Data and Database Issues

Spawn and NPC Issues

Olympiad and Siege Issues

Logging and Debugging

Enable Debug Logging

Common Log Locations

Emergency Procedures

Getting Help

Prevention Best Practices

Related Documentation