uVersion
English
Download →

Wiki

Troubleshooting

Solutions to common problems, on the server side as well as the user side: stuck service, rejected activation code, PostgreSQL, TLS, messages from the client and the Unreal editor.

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

  • Check that 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. First test the database itself, independently of uVersion.

On Linux:

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

On Windows:

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

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

On Linux:

sudo dpkg-reconfigure uversion-server

On Windows: the ordinary install command is enough, the reset triggers on its own as soon as the stored password is missing or refused.

iwr https://uversion.io/downloads/server/install.ps1 -UseBasicParsing | iex

The -Reconfigure parameter only additionally rewrites an existing config.toml, and it requires the long form of the command: the short form above passes no parameter to the script. See Install on Windows.

Port 8443 already in use

uVersion listens on HTTPS on 8443 by default.

There is no HTTP fallback on 8080: the two modes are mutually exclusive The server listens either on HTTPS on tls.https_port (8443 by default), or on plain HTTP on server.port, never both. Plain HTTP exists only if TLS has been explicitly disabled ([tls] disabled = true), and in that case 8443 no longer listens at all. As a result: "nothing is listening on 8443" does not mean "it fell back to 8080", but "TLS is disabled" or "the server didn't start". And a port 8080 that is busy on a normal installation has nothing to do with uVersion.

To find out what is occupying the port, on Linux:

sudo ss -tlnp | grep 8443

On Windows, in two steps: the owning process, then its name.

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). The most frequent causes:

  • First connection not confirmed: the desktop client shows the Verify server identity window with the SHA-256 fingerprint. Compare it with the one the administrator gave you, then click Trust this server. On the CLI, the equivalent command is uversion trust <url>: it is interactive, it shows the fingerprint the server advertises and waits for your confirmation at the keyboard. Add --yes to skip this confirmation, in a script for example.
  • Fingerprint changed (red warning): the server was reinstalled and regenerated its certificate. Confirm with the administrator through another channel, 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 is indeed listening on 8443. On Linux: 
    ss -tlnp | grep 8443
    On Windows: 
    Get-NetTCPConnection -LocalPort 8443 -State Listen
    If nothing is listening, check that [tls] disabled = false in config.toml (that's the default). Reminder: when TLS is disabled, the server switches to plain HTTP and 8443 no longer listens at all, there is no dual listening.
  • Redisplay the fingerprint on the server side, on Linux: 
    sudo cat /var/lib/uversion/data/tls/fingerprint
    On Windows: 
    Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

User side: messages from the client and the editor

The sections above concern the server. Here are the blockers that users run into, with the exact message as it appears and what to do.

I can't create a repository

Admin role required

Creating a repository is reserved for the server's super administrator. The project_admin role is not enough: it administers the projects entrusted to it, it does not create them. Ask your super administrator to create the repository and then make you its administrator.

Opening a local folder fails

Not a uVersion repository

The chosen folder does not contain a .uversion/config.toml. You have probably pointed at the parent folder, or a subfolder. Aim for the workspace root, the one that contains the .uversion/ folder.

Creating a repository from an existing folder fails

This folder is already a uVersion repository - use "Open Local Repository" instead.

The folder is already a workspace. You are not trying to create a new one, but to reopen that one: use Open Local Repository.

The client refuses to open a workspace

This workspace belongs to '<owner>'. Clone your own copy instead.

This folder was cloned by another account, whose name is recorded in .uversion/config.toml. This happens when you copy a workspace from one machine to another, or when you switch accounts in the client. The refusal is deliberate: operating under another identity would produce locks and commits attributed to the wrong person. Clone your own copy. If it really is your folder but the other account is also yours, switch to it in the account selector.

The Unreal Engine path is refused

Invalid Unreal Engine path: '...' is not a recognizable engine install

The client expects the root of an Unreal installation, the one that contains both Engine/Build/BatchFiles and Engine/Binaries. For example C:\Program Files\Epic Games\UE_5.6, and not the Engine subfolder, nor your project folder, nor a shortcut.

An Unreal action refuses to start

Unreal Engine path not configured. Please set it first.

Auto-detection found nothing. Set the path via the " … " menu on the Unreal bar, entry Set Engine Path.... There is no other entry point: no input field, no Browse button in the bar itself.

If the Unreal bar is entirely absent, it is not the engine path: the client did not find the .uproject. It only looks for it three levels deep under the workspace root, and beyond that it disappears with no message. Move the project closer to the root.

Unreal refuses my code submission

Code files must be submitted from the uVersion desktop client

The plugin refuses the checkin of .cpp, .h, .hpp, .c and .cs files: the desktop client compiles before submitting and publishes the editor binaries. Submit your code from the client.

You have code files checked out (...): submit your code from the uVersion desktop client first

A far more confusing variant, which strikes even people who do not write code: a single code file you have checked out also blocks your content submissions, even if that file is not part of the submission. Open the Pending tab of the desktop client, Your locks section, and do a Checkin or a Revert on the code files lingering there. See Unreal Engine plugin.

Unreal doesn't see the server

The editor shows a notification asking to start the desktop client. This is expected: a uVersion server is self-signed by default, and Unreal does not know how to validate a self-signed certificate. The login form of the Revision Control Login window does not get past this obstacle, filling it in is pointless. Start the desktop client, log in with the account that owns the workspace, and the plugin will go through it.

Locking files fails

Failed to acquire locks for {n} file(s). Another user may have them checked out.

Someone else holds those locks. The Pending tab, Other Users' Locks section, says who, and offers a Request Release button per row. Useful reminder: a lock never expires, no one will release it by the mere passage of time. An administrator can force the unlock, and the operation is tracked in the audit.

The command-line clone refuses the folder

Directory '...' already exists and is not empty

uversion clone requires an empty or nonexistent destination folder. Empty it, delete it, or aim for another path. Not to be confused with the desktop client, where the folder you choose is the parent: it creates a subfolder inside it named after the workspace.

Session expired

The client first tries to renew the token silently. If it can't, it returns to the login page with a banner. Simply re-enter your password. If this keeps happening, it is usually because the account has been deactivated on the server side, or an explicit logout has revoked the tokens of all your clients.

Full reset

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