Troubleshooting

`Failed to load TOML config: ./config/main/Server.toml`

The working directory is wrong. The JVM must be launched from the directory that contains the config/ folder. Check your start script — the -cp argument does not set the working directory.

# Correct — run from server root
cd /opt/l2jevo
java -cp "bin/*:lib/*" l2r.gameserver.GameServer

# Wrong — running from bin/
cd /opt/l2jevo/bin
java -cp "*:../lib/*" l2r.gameserver.GameServer  ← config/ not found

`Communications link failure`

Database connection failed. Check:

MariaDB / MySQL is running: systemctl status mariadb
config/main/Server.toml — URL, Login, Password are correct
The DB user has the required GRANT on the target database
Port 3306 is not blocked by a firewall

mysql -u l2juser -p -e "SELECT 1;"   ← test credentials manually

`illegal character '\ufeff'`

A source file or config file was saved with a UTF-8 BOM. Java does not accept BOM at the start of a file. Re-save the file as UTF-8 without BOM.

In PowerShell 5.x, Set-Content -Encoding UTF8 writes a BOM. Use [System.IO.File]::WriteAllText(path, content, (New-Object System.Text.UTF8Encoding $false)) instead.

Engine module does not start

The module's enable flag in its config file defaults to false. Set it explicitly:

# config/l2jdrmods/PremiumService.toml
[service]
UsePremiumServices = true

If the key is missing entirely, Boolean.parseBoolean(null) returns false. Always define every key explicitly.

`ClassNotFoundException` on startup

The Engine classes are not on the JVM classpath. Make sure both bin/ directories are included:

-cp "L2JEvolution.HighFive/bin:L2JEvolution.Engine/bin:lib/*"

`Address already in use: 7777`

A previous server process is still running.

# Linux
ss -tlnp | grep 7777
kill <pid>

# Windows
netstat -ano | findstr 7777
taskkill /PID <pid> /F

Geodata errors / players walk through walls

Check GeoDataPath in config/main/GeoEngine.toml. The path must point to the folder containing .l2d or .l2j geodata files. Missing geodata does not crash the server — AI pathfinding silently skips checks, allowing movement through walls.

OutOfMemoryError: Java heap space

Increase -Xmx. With all Engine modules enabled and 300+ active players, 4 GB is the practical minimum. At 500+ players, allocate 6–8 GB.

java -Xms4g -Xmx8g -XX:+UseZGC -XX:+ZGenerational ...

Troubleshooting

Failed to load TOML config: ./config/main/Server.toml

Communications link failure

illegal character '\ufeff'