Troubleshooting¶
Let's Encrypt: permission denied¶
Run xvei apply after updating xvei. For managed TLS inbounds, xvei copies
the certificate and key to /etc/xray/certs (directory 750, files 640,
owner root:xraycert) and grants Xray the supplementary group through systemd.
Certbot's files and permissions stay unchanged. The renewal hook refreshes
the copies before restarting services, including after xvei remove.
Custom systemd restrictions such as InaccessiblePaths may need separate adjustment.
Start here¶
xvei status # summary and which services run
xvei show-config # the Xray config
xvei firewall status # which ports are blocked
If a change broke something, roll it back: xvei backup restore 1.
Logs¶
| what | command |
|---|---|
| Xray | journalctl -u xray -n 50 |
| nginx (website) | journalctl -u nginx -n 50 |
| Hysteria2 | journalctl -u hysteria-server -n 50 |
| Turnable | journalctl -u turnable -n 50 |
| TOR | journalctl -u tor -n 50 |
| WARP | docker logs warp-xray --tail 50 |
| certificate | /var/log/letsencrypt/letsencrypt.log |
The client does not connect¶
- Ports —
xvei firewall status, and the firewall in your provider's control panel (xvei cannot see it). - Old link — re-adding an inbound changes its link. Take a fresh one:
xvei links. - Old app — REALITY and XHTTP need a recent version.
- VMess only — the server clock must be accurate:
timedatectl set-ntp true. - Trojan TCP only — the link must have
alpn=http/1.1(links from xvei have it).
"certbot failed; falling back to a self-signed certificate"¶
Let's Encrypt could not check the domain, and clients will not accept the temporary certificate.
- The domain must point to this server:
dig +short your.domain. - Port
80/tcpmust be open, including in the provider's panel. - Then run
xvei apply.
"the changed config failed validation"¶
The change did not pass the check and was not applied; Xray keeps the previous
config. The reason is printed above. If you edited config.json by hand, the
mistake may be there:
xray run -test -config /usr/local/etc/xray/config.json.
"xray did not come up; rolling back"¶
The config is valid but Xray did not start, usually because another program
uses the port: journalctl -u xray -n 50, ss -tulpn.
Turnable¶
- Captcha — open the local address the client prints.
- Stopped working — the external service may have changed something;
xvei check-updatesshows a new Turnable version. - Slow — the external service limits a connection to about 250 KB/s.
Start over¶
xvei remove --all
Then install again as in getting started.