Aether Panel Documentation

Troubleshooting Guide

This document details solutions to common problems encountered during the deployment and operation of Aether Panel.

1. Unshare Isolation (Ubuntu 24.04+)

Problema:

Permission denied error when starting the security jail or game server.

Causa:

Ubuntu 24.04+ restricts unprivileged user namespaces (unshare) by default, which the panel uses to isolate game server processes.

Log symptom:

[ERROR] error starting server testserver: fork/exec /bin/bash: operation not permitted

Soluciones:

Option A (Recommended for production):

Enable namespaces in the kernel:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Option B (Disable isolation):

Add to config.json:

{
    "panel": {
        "security": {
            "disableUnshare": true
        }
    }
}

Can also be configured per server in its individual JSON with "disableUnshare": true in the environment (tty) section.

2. Docker Connection

Problema:

The panel cannot connect to the Docker engine.

Causa:

The panel uses the Docker SDK with client.FromEnv(), which reads standard Docker environment variables.

Log symptom:

[ERROR] Cannot connect to the Docker daemon

Soluciones:

Verify Docker is running:

docker info

Check socket permissions:

The user running the panel must have permissions to access the Docker socket:

sudo usermod -aG docker $USER
# Log out and back in

Use custom Docker socket:

export DOCKER_HOST=unix:///var/run/docker.sock

Running the panel inside Docker:

The panel automatically detects PUFFER_PLATFORM=docker and skips Docker verification, continuing without the internal Docker engine.

3. SFTP — Connection and Authentication

Problema:

Cannot connect via SFTP to the panel.

Default port: 5657

Error: incorrect username or password

Database authentication: User format is email#serverId (e.g. user@example.com#abc123). Verify the user has the ScopeServerSftp permission assigned.
OAuth2 authentication: Verify the OAuth2 authentication server is accessible and returns the sftp scope for the corresponding server.

Error: error talking to auth server

Verify that daemon.auth.url points to the correct panel URL (default: http://localhost:8080).
Verify that daemon.auth.clientId and daemon.auth.clientSecret are configured.

Error: no access / invalid response from authorization server

The OAuth2 server rejected the credentials or the requested scope is not available.

Error: connection refused

The SFTP port (5657) is not open or the panel is not running.
Check with: ss -tlnp | grep 5657

4. Database

Problema:

Database connection error when starting the panel.

Supported dialects: sqlite3, mysql, postgresql, sqlserver

dial tcp 127.0.0.1:3306: connect: connection refused — MySQL/MariaDB is not running.
could not load driver — Incorrect dialect or driver not compiled.

Soluciones:

For SQLite (recommended for testing):

{
    "panel": {
        "database": {
            "dialect": "sqlite3",
            "url": "skypanel.db"
        }
    }
}

For MySQL/MariaDB:

Verify the service is running and the user has permissions:

mysql -u skypanel -p -h 127.0.0.1 skypanel

For PostgreSQL:

Verify pg_hba.conf allows connections from localhost.

For SQL Server:

Verify that TCP/IP is enabled in the server configuration.

5. Ports in Use

Problema:

Address already in use error when starting the panel.

Default ports:

Service	Port	Config Key
HTTP (Web)	8080	web.host
SFTP	5657	daemon.sftp.host

Soluciones:

Check which process is using the port:

ss -tlnp | grep -E '8080|5657'

Change port in config.json:

{
    "web": {
        "host": "0.0.0.0:9090"
    },
    "daemon": {
        "sftp": {
            "host": "0.0.0.0:6565"
        }
    }
}

Via environment variables:

export PUFFER_WEB_HOST=0.0.0.0:9090
export PUFFER_DAEMON_SFTP_HOST=0.0.0.0:6565

6. File Permissions (UID/GID)

Problema:

Files created by the panel have incorrect owners or permission errors.

Comportamiento:

The panel assigns UID/GID to server files according to the configured user. If UID is -1, ownership is not changed (uses the process user).

Soluciones:

Check the panel process UID/GID:

ps aux | grep skypanel

Docker containers inherit the panel process UID/GID automatically.

TTY environment with unshare: The process inside the jail runs as root (UID 0) mapped to the real system user. Files created inside the jail will belong to the real user outside the jail.

If there are permission errors reading/writing server files, verify the panel user has access to the servers/, cache/ and binaries/ directories.

7. CORS — Frontend Connections

Problema:

The frontend cannot make requests to the API (CORS errors in browser console).

Comportamiento:

The panel allows all origins (AllowOriginFunc always returns true). This is intentional to support deployments where frontend and backend are on separate domains.

Soluciones:

If there are CORS errors, verify the frontend is using the correct API URL.

Verify that Authorization and Content-Type headers are included in requests.

If using a reverse proxy (nginx, Caddy) that modifies headers, make sure it does not remove CORS headers.

8. Environment Variables and Configuration

Problema:

The panel does not use the values you configured.

Comportamiento:

All config.json settings can be overridden with environment variables using the PUFFER_ prefix and replacing . with _.

Environment Variable	JSON Config
PUFFER_WEB_HOST	web.host
PUFFER_DAEMON_SFTP_HOST	daemon.sftp.host
PUFFER_PANEL_DATABASE_URL	panel.database.url
PUFFER_PANEL_DATABASE_DIALECT	panel.database.dialect
PUFFER_LOGS	logs
PUFFER_PANEL_SETTINGS_COMPANYNAME	panel.settings.companyName

Environment variables take priority over the config.json file.

9. Logs and Debugging

Problema:

You need more information to diagnose an error.

Comportamiento:

The panel writes logs to logs/skypanel.log with automatic rotation on SIGUSR1.

Log levels:

Prefix	Level	Destination
[ERROR]	Error	Stderr + file
[INFO]	Info	Stdout + file
[DEBUG]	Debug	Stdout + file
[SERVER]	Server	Stdout + file

Soluciones:

View logs in real time:

tail -f logs/skypanel.log

Force log rotation (without restarting):

kill -USR1 $(pidof SkyPanel)

Increase debug level:

Start with GIN_MODE=debug to see all HTTP routes:

GIN_MODE=debug ./SkyPanel run

10. SSL/TLS (HTTPS)

Problema:

You need HTTPS for production.

Comportamiento:

The panel does not include native HTTPS support. It only listens on plain HTTP.

Use a reverse proxy for SSL termination (nginx, Caddy, Traefik):

Example with Caddy:

panel.yourdomain.com {
    reverse_proxy localhost:8080
}

Example with nginx:

server {
    listen 443 ssl;
    server_name panel.yourdomain.com;

    ssl_certificate /etc/ssl/certs/panel.crt;
    ssl_certificate_key /etc/ssl/private/panel.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Trusted proxy configuration:

{
    "security": {
        "trustedProxies": ["127.0.0.1/32", "10.0.0.0/8"],
        "trustedProxyHeader": "X-Forwarded-For"
    }
}

11. Database Migrations

Problema:

Error running migrations or the panel does not start after an update.

Soluciones:

Run migrations manually:

This command performs an automatic backup before migrating.

./SkyPanel db upgrade

If migration fails, verify the database user has permissions to create/modify tables.

SQLite: The skypanel.db file must have write permissions for the panel user.

12. Templates

Problema:

The panel loads the template index but fails to download individual templates.

Causa:

The URL configured in templates.url points to a server that only has the templates.json but not the individual JSON files for each template.

Make sure the template server has the complete structure. If templates.json references minecraft/minecraft.json, that file must be accessible at the same base path.

13. AI Assistant (Google GenAI)

Problema:

The AI assistant does not respond or shows errors.

Causa:

The Google Gemini API Key has not been configured.

Configure in config.json:

{
    "panel": {
        "settings": {
            "geminiApiKey": "your-gemini-api-key"
        }
    }
}

Or via environment variable:

export PUFFER_PANEL_SETTINGS_GEMINIAPIKEY=your-gemini-api-key

14. Configuration File

Problema:

The panel cannot find or ignores the configuration file.

Comportamiento:

By default, the panel looks for config.json in the current working directory. A custom path can be specified with the --config flag or the PUFFER_CONFIG environment variable.

config.jsonMain configuration (customizable).

config.docker.jsonPredefined configuration for Docker environment.

config.linux.jsonPredefined configuration for Linux (local SQLite).

./SkyPanel run --config config.linux.json

15. General Troubleshooting

Pasos:

Check the full logs:

cat logs/skypanel.log | grep ERROR

Check the panel version:

./SkyPanel version

Check network connectivity: Ensure the necessary ports (8080, 5657) are accessible from clients.

Check disk space: The panel needs space for logs, template cache, and game servers.

Report the problem

on Discord (https://discord.gg/aetherpanel) or open an issue on GitHub (https://github.com/Aether-Panel/Panel/issues) including the relevant logs.

AnteriorFAQ SiguienteSupport