Skip to main content

Common Errors

Below are the problems encountered most often. The format is the same: symptom → cause → fix. Start with the logs — almost always the cause is visible there:

docker compose logs --tail=100 xpanel
docker compose ps
tip

The full set of diagnostic commands is in Useful Commands.

A quick cheat sheet: what you see — what to look at.

Symptom in the log or interfaceLikely cause
Reverse proxy and HTTPS are requiredno X-Forwarded-* headers from the proxy
❌ METRICS_USER / ❌ METRICS_PASSmetrics variables are not set
Node does not connectNODE_PORT is closed or SECRET_KEY is incomplete
address already in usethe port is taken by another process
certbot failsDNS, port 80, or a foreign server_name
xpanel-db in the unhealthy state.env, the volume, or the PostgreSQL version
502 Bad Gateway from nginxthe panel is not listening on 127.0.0.1:3000
Sign-in stopped workingAPP_SECRET was changed

"Reverse proxy and HTTPS are required"​

Symptom. The panel does not open, and the xpanel log shows the line Reverse proxy and HTTPS are required.

Cause. The request reached the panel without the X-Forwarded-For and X-Forwarded-Proto: https headers. The panel code has middleware that drops the connection in this case.

Fix. Make sure the nginx config in front of the panel has both lines:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Open the panel over https://, not http://. If TLS terminates earlier (on a CDN or load balancer), do not replace X-Forwarded-Proto with the value http. Ready-made configs are in Reverse Proxy.

METRICS_USER and METRICS_PASS are not set​

Symptom. The xpanel container restarts, and the log shows ❌ METRICS_USER or ❌ METRICS_PASS.

Cause. The metrics variables are required: without them the panel does not start.

Fix. Add them to /opt/xlada/.env and restart the stack:

METRICS_USER=xpanel
METRICS_PASS=<strong password>
docker compose up -d

Node does not appear in the panel​

Symptom. The node is created but stays disconnected in the panel.

Cause. Usually one of three: NODE_PORT is unreachable from the panel server, SECRET_KEY was not copied in full, or the node container did not start.

Fix. Check in order:

  1. docker logs -f xpanel-node — with a wrong key, the node prints the cause itself.
  2. From the panel server: nc -vz <node ip> 2222.
  3. Make sure the key is pasted in full, without line breaks.
  4. Open port 2222 in the firewall only for the panel IP.

See Node Installation for details.

note

Each node has its own SECRET_KEY and its own certificate. A shared key for several servers is not supported — you must not move it from one node to another.

Port conflict​

Symptom. The container does not start with address already in use, or Xray on the node does not listen on the given port.

Cause. The port is taken by another process: 3000, 3001, 3010 on the panel server, or an inbound port on the node.

Fix. Find the owner of the port and free it:

ss -tlnp | grep -E ':(3000|3001|3010|2222)\b'

If changing the port is easier than freeing it, edit APP_PORT or METRICS_PORT in .env and remember to update proxy_pass in nginx. On the node, check that the container runs with --network host: port forwarding breaks real client IP detection.

Certificate is not issued​

Symptom. certbot --nginx -d panel.example.com fails.

Cause. The domain does not point to this server, port 80 is closed, or the domain is already served by another virtual host.

Fix.

dig +short panel.example.com   # must return the panel server IP
ss -tlnp | grep ':80'
certbot certificates           # what is already issued
certbot renew --dry-run        # test auto-renewal

Check server_name in the nginx config, then run nginx -t && systemctl reload nginx. Make sure the auto-renewal timer is active: systemctl list-timers | grep certbot.

Database does not come up​

Symptom. xpanel waits for the database and crashes, xpanel-db is in the unhealthy state or keeps restarting.

Cause. Most often a wrong DATABASE_URL, a POSTGRES_PASSWORD mismatch with an existing volume, or an incompatible PostgreSQL major version on an old data directory.

Fix.

docker compose ps
docker compose logs --tail=100 xpanel-db
docker exec xpanel-db pg_isready -U xpanel -d xpanel

Check POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and DATABASE_URL. Do not rename volumes and services: on the next start, compose will create new empty ones. The PostgreSQL data directory is incompatible between major versions, so moving to a new version is done only through a dump and restore — see Migrating from Remnawave.

502 Bad Gateway from nginx​

Symptom. nginx returns 502 on https://panel.example.com.

Cause. There is nobody behind proxy_pass: the panel container is not running, did not complete migrations, or listens on a different port.

Fix.

docker compose ps
curl -sI http://127.0.0.1:3000
docker compose logs --tail=100 xpanel

Wait for the XLADA Backend v1.1.7 and Nest application successfully started lines in the log. If APP_PORT was changed, fix proxy_pass http://127.0.0.1:<port> and reload nginx.

Sign-in does not work after changing APP_SECRET​

Symptom. The administrator password no longer works, TOTP codes are not accepted, and active sessions are reset.

Cause. APP_SECRET was changed after the first start. Password hashes, JWT, and TOTP secret encryption depend on it. The same effect comes from the change_me value left in .env.

Fix. Restore the previous APP_SECRET value from a .env backup and run docker compose up -d. If the original is lost, the only way in is a reset through the database. Generate the secret in advance (openssl rand -hex 32) and keep it in a secrets manager — see Panel Security.

What's next​