Troubleshooting

Common issues and how to solve them.

Quick Checks

Before diving into specific problems, try these:

~/quick-checks● LIVE

$docker compose ps

NAME STATUS PORTS

minepanel-frontend Up 0.0.0.0:3000->3000/tcp

minepanel-backend Up 0.0.0.0:8091->8091/tcp

Tip: run docker compose logs --tail 100 if any service is down

# Check if containers are running
docker compose ps

# View logs
docker compose logs minepanel
docker compose logs --tail 100

# Check Docker daemon
docker ps

# Restart everything
docker compose restart

Installation Issues

Worlds tab does not show my world

Symptoms: Worlds list is empty or missing entries.

Checklist:

1. Upload world sources to either:
   • servers/<server-id>/worlds/ (local)
   • servers/.world/worlds/ (World Library, global)
2. Supported formats:
   • Folder containing level.dat
   • .zip, .tar, .tar.gz, .tgz
3. If the world is inside nested folders, ensure one of them contains level.dat
4. For Discover Worlds imports, only archive files are accepted (.zip, .tar, .tar.gz, .tgz)
5. CurseForge search/import requires a configured API key in Settings

World switch applied but server starts old world

Symptoms: You select a world, restart, but old level remains.

Cause: By default, WORLD only copies if target level doesn't exist.

Solution:

• Enable Force world copy in the Worlds tab (FORCE_WORLD_COPY=TRUE)
• Or choose a different LEVEL name so a new target folder is created

Docker Not Found

Error: docker: command not found or docker compose: command not found

Solution:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then test
docker --version
docker compose version

Permission Denied

Error: permission denied while trying to connect to the Docker daemon socket

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or:
newgrp docker

# Verify
docker ps

Port Already in Use

Error: port is already allocated or address already in use

Solution:

# Find what's using the port
sudo lsof -i :3000
sudo lsof -i :8091

# Option 1: Stop the conflicting service
sudo systemctl stop <service-name>

# Option 2: Change Minepanel ports
# Edit docker-compose.yml or .env
FRONTEND_PORT=3001
BACKEND_PORT=8092

# Restart
docker compose down
docker compose up -d

Connection Issues

Can't Access Frontend

Symptoms: Browser shows "Can't connect" or "Connection refused"

Solutions:

1. Check container is running:

docker compose ps
# Should show minepanel as "Up"

2. Check logs:

docker compose logs minepanel

3. Verify port:

# Check if port is open
curl http://localhost:3000

4. Firewall:

# Allow port through firewall
sudo ufw allow 3000/tcp

Can't Access from Remote

Symptoms: Works on localhost but not from other devices

Solutions:

1. Update FRONTEND_URL:

environment:
  - FRONTEND_URL=http://YOUR_IP:3000 # Not localhost!

2. Firewall configuration:

# Ubuntu/Debian
sudo ufw allow 3000/tcp
sudo ufw allow 8091/tcp
sudo ufw allow 8080/tcp

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=8091/tcp
sudo firewall-cmd --reload

3. Check router port forwarding (if accessing from internet)

4. Restart after changes:

docker compose restart

CORS Errors

Symptoms: Console shows CORS policy errors, API calls fail

Solution:

The FRONTEND_URL must match EXACTLY how you access the frontend:

# If accessing via http://localhost:3000
FRONTEND_URL=http://localhost:3000

# If accessing via http://192.168.1.100:3000
FRONTEND_URL=http://192.168.1.100:3000

# If accessing via domain
FRONTEND_URL=https://minepanel.yourdomain.com

Always restart after changing:

docker compose restart

Authentication Issues

Can't Login

Error: "Invalid credentials" with correct password

Solutions:

1. Check if first time login:

If no user exists yet, Minepanel should show the initial admin registration screen instead of the login form.

2. Password changed in UI:

If SMTP is configured and your account has an email, use the login page recovery flow or Administration.

3. Database issues:

# Check if database exists
ls -l data/minepanel.db

# If missing, recreate
docker compose down
docker compose up -d

4. Reset password:

See Password Management.

Stuck on "Verifying authentication..."

Symptoms: Login appears successful, but dashboard keeps loading on "Verifying authentication...".

Cause: Browser is rejecting auth cookies because they are marked Secure while the panel is being accessed over plain HTTP.

Quick checks:

1. Open browser DevTools → Network and inspect /auth/me response (usually 401 in this case).
2. Open DevTools → Application/Storage → Cookies and verify whether access_token/refresh_token are being stored.

Solutions:

1. Recommended: Use HTTPS and set FRONTEND_URL / NEXT_PUBLIC_BACKEND_URL to https://....
2. HTTP fallback (LAN/dev only): Enable insecure auth cookies explicitly:

environment:
  - ALLOW_INSECURE_AUTH_COOKIES=true

Then restart Minepanel:

docker compose restart

JWT Token Errors

Error: "Invalid token" or "Token expired"

Solutions:

1. Clear browser cache and cookies
2. Log out and log back in
3. Check JWT_SECRET hasn't changed:

environment:
  - JWT_SECRET=same_secret_as_before

Server Management Issues

Can't Create Server

Error: Server creation fails

Solutions:

1. Check Docker socket access:

ls -l /var/run/docker.sock
# Should be readable by Docker group

2. Check BASE_DIR:

environment:
  - BASE_DIR=/absolute/path # Must be absolute!

3. Check disk space:

df -h

4. View detailed error:

docker compose logs minepanel | grep -i error

Server Data Goes to the Wrong Host Folder

Symptoms: A created server runs, but its files land somewhere other than where you mounted the data, or the generated docker-compose.yml points at a path that doesn't exist on the host.

Cause: BASE_DIR (the host path that maps to /app) didn't match where you actually mounted the data. Generated server compose files use host paths derived from it.

Solution: This is now auto-detected — Minepanel reads the real host source of the /app/servers mount at startup, so you can leave BASE_DIR unset and it will match your mount. If you previously hardcoded it to a wrong value, remove it (or fix it) and recreate the affected servers. If you set BASE_DIR and it differs from the detected path, the startup logs will warn you and the detected path wins. See Configuration → Base Directory.

Server Won't Start

Symptoms: Server status shows "error" or "exited"

Solutions:

1. Check server logs:

# Via UI: Go to server → Logs tab

# Via terminal:
docker logs <server-container-name>

2. Common issues:

Port conflict:

# Find what's using the port
sudo lsof -i :25565

# Change server port in Minepanel

Memory limits:

# Increase memory in server settings
MAX_MEMORY: 4G
INIT_MEMORY: 2G

EULA not accepted:

# Check if EULA=TRUE in server config
# Recreate server if needed

3. Restart Docker:

sudo systemctl restart docker
docker compose restart

Server Stuck in "Starting"

Solutions:

1. Give it more time - First start can take 5-10 minutes
2. Check logs for actual progress
3. Check resources:

docker stats
# Ensure enough CPU/RAM available

4. Force restart:

docker restart <server-container-name>

Mod/Plugin Issues

Mods Not Downloading

Symptoms: Modrinth or CurseForge mods don't appear

Solutions:

1. Check API key (for CurseForge):

environment:
  CF_API_KEY: your_actual_key

2. Check server logs:

docker logs <server-name> | grep -i "modrinth\|curseforge"

3. Verify project names:

• Test on Modrinth website first
• Check spelling of project slugs
• Ensure compatibility with Minecraft version

4. Network issues:

# Test connectivity from container
docker exec <server-name> ping modrinth.com
docker exec <server-name> ping api.curseforge.com

Version Conflicts

Symptoms: Server crashes, "incompatible" errors

Solutions:

1. Check Minecraft version matches mods
2. Verify loader version (Fabric/Forge/Neoforge)
3. Check mod dependencies
4. Remove conflicting mods one by one

File Browser Issues

Can't Upload Files

Solutions:

1. Check permissions:

ls -ld servers/your-server/mc-data
# Should be writable

2. Check disk space:

df -h

Can't Edit Files

Symptoms: Changes don't save

Solutions:

1. Stop server first before editing critical files
2. Check file permissions
3. Use correct file encoding (UTF-8)

Performance Issues

High CPU Usage

Solutions:

1. Limit server resources:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G

2. Use Aikar's flags:

environment:
  USE_AIKAR_FLAGS: 'true'

3. Reduce view distance:

environment:
  VIEW_DISTANCE: 6
  SIMULATION_DISTANCE: 4

High Memory Usage

Solutions:

1. Increase swap:

# Check current swap
free -h

# Add swap
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. Lower server memory allocation
3. Use Paper/Purpur instead of Vanilla

Slow Response Times

Solutions:

1. Use SSD instead of HDD
2. Increase server resources
3. Enable auto-pause for idle servers:

environment:
  ENABLE_AUTOPAUSE: 'true'
  AUTOPAUSE_TIMEOUT_EST: 3600

Database Issues

Database Locked

Error: "database is locked"

Solution:

# Stop all containers
docker compose down

# Wait a few seconds
sleep 5

# Start again
docker compose up -d

Corrupted Database

Symptoms: Errors loading servers, UI broken

Solutions:

1. Restore from backup:

docker compose down
cp data/minepanel.db.backup data/minepanel.db
docker compose up -d

2. If no backup, reset: (loses all data)

docker compose down
rm data/minepanel.db
docker compose up -d

Docker Issues

Container Keeps Restarting

Solutions:

1. Check logs:

docker compose logs --tail 100

2. Check for crashes:

docker inspect minepanel | grep -A 10 "State"

3. Verify environment variables:

docker compose config

Can't Pull Image

Error: "error pulling image configuration"

Solutions:

1. Check internet connection
2. Check Docker Hub status
3. Clear Docker cache:

docker system prune -a

4. Manual pull:

docker pull ketbom/minepanel:latest

Bedrock-Specific Issues

Can't Connect to Bedrock Server

Symptoms: Minecraft client shows "Unable to connect to world"

Solutions:

1. Check UDP port is open:

# Bedrock uses UDP, not TCP!
sudo ufw allow 19132/udp

# Check firewall
sudo ufw status

2. Port forwarding:

If accessing from internet, ensure router forwards UDP port.

3. LAN visibility:

environment:
  ENABLE_LAN_VISIBILITY: 'true'

4. Online mode:

If using Xbox Live accounts, ensure ONLINE_MODE=true.

Bedrock Commands Not Working

Symptoms: Commands sent but nothing happens

Solutions:

1. Check server logs - Bedrock command output goes to logs, not the console response:

docker logs <bedrock-server-name> --tail 50

2. Verify command syntax:

# Correct
docker exec CONTAINER send-command say Hello

# Not RCON - Bedrock doesn't support RCON

Bedrock Server Stuck Starting

Solutions:

1. EULA acceptance:

environment:
  EULA: 'TRUE'

2. Version issues:

environment:
  VERSION: LATEST # or specific like "1.21.0.03"

3. Check logs for specific error:

docker logs <bedrock-server-name>

Command & Auto-Stop Issues

Server Restarts After Auto-Stop

Symptoms: Server stops due to Auto-Stop, then container starts again immediately.

Cause: Restart policy is incompatible with Auto-Stop.

Solution:

1. Enable Auto-Stop from the UI.
2. Confirm restart policy is set to No restart.
3. Save configuration.

Minepanel now enforces this rule automatically on save (enableAutoStop=true => restartPolicy=no).

Command Fails with Strange Characters / Malformed Input

Symptoms: Commands fail unexpectedly, especially after paste from terminal/chat tools.

Cause: Hidden control or ANSI characters in command input.

Solution:

• Re-type or paste plain text command.
• Minepanel now normalizes command input (trim + control-char removal).
• Empty commands after normalization are rejected as invalid payload.

Console Response Shows Color Codes

Symptoms: Response includes raw ANSI sequences like \x1b[32m.

Solution:

Minepanel now strips ANSI escape sequences from command responses before returning them to the frontend.

---

Still Having Issues?

Collect Debug Information

# System info
uname -a
docker --version
docker compose version

# Container status
docker compose ps

# Recent logs
docker compose logs --tail 200 > minepanel-logs.txt

# System resources
docker stats --no-stream

# Disk space
df -h

Get Help

1. Check the FAQ for common questions
2. Search GitHub Issues
3. Create a new issue with:
   • Your debug information
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots if applicable

Emergency Reset

If nothing works and you need to start fresh:

DANGER

This removes EVERYTHING!

# Stop everything
docker compose down -v

# Remove all data
rm -rf data/ servers/

# Remove images
docker rmi ketbom/minepanel

# Start fresh
docker compose up -d

Next Steps

• Review Administration Guide
• Check Configuration Reference
• Join the community for support