Wiki

Troubleshooting

Solutions to common problems: stuck service, rejected activation code, PostgreSQL, TLS.

The service won't start

Linux: systemctl start fails

sudo journalctl -u uversion-server -n 100 --no-pager

Common causes:

PostgreSQL not running: sudo systemctl status postgresql
Lost DB password: the postinst regenerates the config with --reconfigure (sudo dpkg-reconfigure uversion-server)
Port 8443 in use: see the dedicated section below

Windows: error 1053 or 1067

The service starts then stops. Check the Event Viewer:

Get-EventLog -LogName Application -Source uVersionServer -Newest 50

Common causes:

Missing CONFIG_PATH environment variable: normally set by the installer in HKLM\SYSTEM\CurrentControlSet\Services\uVersionServer\Environment
PostgreSQL not running: Get-Service postgresql*

The activation code is rejected

Make sure the code hasn't been used on another machine (each code is tied to the server-ID of the first install). Request a new code from your account area.
Check connectivity to licence.uversion.io: curl -I https://licence.uversion.io/api/v1/health
If you want to reuse a code on a new machine after uninstalling, contact support to release the previous server-ID.

PostgreSQL unreachable

The uVersion service can't connect to the database. Test manually:

# Linux
sudo -u postgres psql -c "SELECT 1;"

# Windows
& "C:\Program Files\PostgreSQL\16\bin\psql.exe" -U postgres -h 127.0.0.1 -c "SELECT 1;"

If PostgreSQL is installed but the superuser password is lost, the uVersion installer (Linux postinst as well as Windows install.ps1) can put PostgreSQL back into trust mode automatically, reset the password, then restore the original config. Re-run:

# Linux
sudo dpkg-reconfigure uversion-server

# Windows
iwr https://uversion.io/downloads/server/install.ps1 -UseBasicParsing | iex
# (re-passe par le script avec -Reconfigure)

Port 8443 already in use

uVersion listens on HTTPS on 8443 by default (and keeps 8080 open as an HTTP fallback). If either one is taken:

# Linux
sudo ss -tlnp | grep -E '8443|8080'

# Windows
Get-NetTCPConnection -LocalPort 8443 | Select-Object OwningProcess, State
Get-Process -Id <PID>

To change the TLS port, edit config.toml:

[tls]
https_port = 9443

Then restart the service.

Client refuses the TLS connection

uVersion uses a self-signed certificate locked via TOFU on the client side (see TLS fingerprint). Most common causes:

First connection not confirmed: the desktop client shows a dialog with the fingerprint. Compare it with what the admin shared with you. On the CLI, run uversion trust <url>.
Fingerprint changed (red warning): the server was reinstalled and regenerated its certificate. Confirm out-of-band with the admin, then:
- Desktop: click Trust new fingerprint in the red dialog
- CLI: uversion mistrust <url> then uversion login <url>
The server isn't serving HTTPS: check that it's actually listening on 8443, not 8080:
```
# Linux
ss -tlnp | grep 8443
# Windows
Get-NetTCPConnection -LocalPort 8443 -State Listen
```
If nothing is listening, check that [tls] disabled = false in config.toml (that's the default).

Redisplay the fingerprint on the server side:

# Linux
sudo cat /var/lib/uversion/data/tls/fingerprint
# Windows
Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

Full reset

See the Ubuntu/Debian uninstall or Windows uninstall pages to start from a clean install.