トラブルシューティング

サービスが起動しない

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

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

アクティベーションコードが拒否される

• コードが別のマシンで使用されていないか確認してください （各コードは最初のインストール時の server-ID に紐付けられます）。新しい コードはアカウントページから請求してください。
• licence.uversion.io への接続を確認してください： curl -I https://licence.uversion.io/api/v1/health
• アンインストール後に新しいマシンでコードを再利用したい場合は、 サポートに連絡して以前の server-ID を解放してください。

PostgreSQL に接続できない

uVersion サービスがデータベースに接続できません。まず uVersion とは独立して データベース自体をテストしてください。

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;"

PostgreSQL は応答するがスーパーユーザーのパスワードを紛失した場合、 uVersion インストーラー（Linux の postinst も Windows の install.ps1 も）は PostgreSQL を自動的に trust モードに戻し、パスワードをリセットしてから 元の設定を復元できます。再実行してください。

Linux の場合：

sudo dpkg-reconfigure uversion-server

Windows の場合：通常のインストールコマンドで十分です。保存された パスワードがない、または拒否された時点で、リセットは自動的に実行されます。

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

-Reconfigure パラメーターは、すでに存在する config.toml を 追加で書き換えるためだけのもので、コマンドの完全形が必要です：上記の短い形式ではスクリプトに パラメーターが一切渡されません。 Windows へのインストールを参照してください。

ポート 8443 が使用中

uVersion はデフォルトで 8443 の HTTPS をリッスンします。

どのプロセスがポートを占有しているかを調べるには、Linux の場合：

sudo ss -tlnp | grep 8443

Windows の場合、2 段階で：所有プロセス、次にその名前。

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

TLS ポートを変更するには config.toml を編集してください：

[tls]
https_port = 9443

その後、サービスを再起動してください。

クライアントが TLS 接続を拒否する

uVersion はクライアント側で TOFU によりロックされた自己署名証明書を 使用します（TLS フィンガープリントを参照）。 最もよくある原因：

• 初回接続が未確認：デスクトップクライアントが SHA-256 フィンガープリントを含む Verify server identity ウィンドウを表示します。管理者から伝えられた値と比較し、 Trust this server をクリックしてください。CLI での同等のコマンドは uversion trust <url> です：これは対話的で、サーバーが通知する フィンガープリントを表示し、キーボードでの確認を待ちます。たとえばスクリプト内でこの確認を 省略するには --yes を追加してください。
• フィンガープリントが変更された（赤い警告）：サーバーが再インストールされ、 証明書が再生成されました。別の経路で管理者に確認してから：
  • デスクトップ：赤いダイアログで Trust new fingerprint をクリック
  • CLI：uversion mistrust <url> の後 uversion login <url>
• サーバーが HTTPS を提供していない：8443 で正しくリッスンしているか確認してください。 Linux の場合：

  ss -tlnp | grep 8443

  Windows の場合：

  Get-NetTCPConnection -LocalPort 8443 -State Listen

  何もリッスンしていない場合は、config.toml で [tls] disabled = false になっているか確認してください（これがデフォルトです）。補足：TLS が無効化されると、サーバーは 素の HTTP に切り替わり、8443 はまったくリッスンしなくなります。二重にリッスンすることはありません。
• サーバー側でフィンガープリントを再表示する、Linux の場合：

  sudo cat /var/lib/uversion/data/tls/fingerprint

  Windows の場合：

  Get-Content "C:\ProgramData\uVersion\data\tls\fingerprint"

ユーザー側：クライアントとエディターのメッセージ

上記のセクションはサーバーに関するものです。ここでは、ユーザーが遭遇する行き詰まりを、 表示される正確なメッセージと対処法とともに示します。

リポジトリを作成できない

Admin role required

リポジトリの作成はサーバーのスーパー管理者に限られます。 project_admin ロールでは不十分です：委任されたプロジェクトを管理しますが、作成はしません。 スーパー管理者にリポジトリを作成してもらい、その管理者に任命してもらってください。

ローカルフォルダーを開けない

Not a uVersion repository

選択したフォルダーに .uversion/config.toml がありません。おそらく親フォルダーか、 サブフォルダーを指定しています。.uversion/ フォルダーを含むワークスペースのルートを指定してください。

既存のフォルダーからリポジトリを作成できない

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

そのフォルダーはすでにワークスペースです。新しく作成するのではなく、それを再度開きたいのです： Open Local Repository を使用してください。

クライアントがワークスペースを開かない

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

このフォルダーは別のアカウントによってクローンされており、その名前が .uversion/config.toml に 記録されています。これはワークスペースをマシン間でコピーしたとき、またはクライアントでアカウントを切り替えたときに 発生します。この拒否は意図的です：別の ID で操作すると、間違った人物に帰属するロックとコミットが生じます。 自分自身のコピーをクローンしてください。それが確かに自分のフォルダーで、もう一方のアカウントも自分のものである場合は、 アカウントセレクターでそちらに切り替えてください。

Unreal Engine のパスが拒否される

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

クライアントは Unreal インストールのルート、つまり Engine/Build/BatchFiles と Engine/Binaries の両方を含むものを期待します。たとえば C:\Program Files\Epic Games\UE_5.6 であり、Engine サブフォルダーでも、 プロジェクトフォルダーでも、ショートカットでもありません。

Unreal の操作が開始しない

Unreal Engine path not configured. Please set it first.

自動検出では何も見つかりませんでした。Unreal バーの 「 … 」 メニュー、 Set Engine Path... の項目からパスを設定してください。他の入り口はありません：バー自体に 入力フィールドも Browse ボタンもありません。

Unreal バーがまったく表示されない場合は、エンジンのパスの問題ではありません：クライアントが .uproject を見つけられませんでした。ワークスペースのルートから 3 階層の深さまでしか探さず、 それを超えるとメッセージなしで消えます。プロジェクトをルートに近づけてください。

Unreal がコードの送信を拒否する

Code files must be submitted from the uVersion desktop client

プラグインは .cpp、.h、.hpp、.c、 .cs ファイルのチェックインを拒否します：デスクトップクライアントは送信前にコンパイルし、エディターのバイナリを公開します。 コードはクライアントから送信してください。

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

はるかに紛らわしい別のパターンで、コードを書かない人にも影響します：あなたが予約した コードファイルが 1 つあるだけで、コンテンツの送信もブロックされます。そのファイルが送信に含まれていなくても同様です。 デスクトップクライアントの Pending タブ、Your locks セクションを開き、そこに残っている コードファイルに対して Checkin または Revert を実行してください。 Unreal Engine プラグインを参照してください。

Unreal がサーバーを認識しない

エディターがデスクトップクライアントの起動を求める通知を表示します。これは想定内です：uVersion サーバーは デフォルトで自己署名されており、Unreal は自己署名証明書を検証できません。Revision Control Login ウィンドウの ログインフォームはこの障害を越えられないため、入力しても意味がありません。デスクトップクライアントを起動し、 ワークスペースの所有者アカウントでログインすれば、プラグインはそれを経由します。

ファイルの予約が失敗する

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

他の誰かがこれらのロックを保持しています。Pending タブの Other Users' Locks セクションが 誰かを示し、行ごとに Request Release ボタンを提供します。役立つ補足：ロックは決して 期限切れになりません。時間の経過だけで解放する人はいません。管理者は強制的にロックを解除でき、 その操作は監査に記録されます。

コマンドラインのクローンがフォルダーを拒否する

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

uversion clone は、空または存在しない宛先フォルダーを必要とします。空にするか、削除するか、 別のパスを指定してください。デスクトップクライアントと混同しないでください。そちらでは選択するフォルダーが 親です：その中にワークスペース名のサブフォルダーを作成します。

セッションの有効期限切れ

クライアントはまずトークンを黙って更新しようとします。できない場合は、バナー付きのログインページに 戻ります。パスワードを再入力するだけです。これが繰り返し発生する場合、通常はサーバー側でアカウントが 無効化されたか、明示的なログアウトによってすべてのクライアントのトークンが取り消されたためです。

完全リセット

クリーンインストールからやり直すには、Ubuntu/Debian のアンインストール または Windows のアンインストール ページを参照してください。