エラーを読んで直す

最初に、エラーのメッセージを控える

このページは、起動したときや実行中に、例外やエラーのログが出たときの手順です。出ているメッセージから原因を探し、直す操作を 1 つ行います。

最初に、コンソールに出ているメッセージを控えます。控えるのは次の 3 つです。

例外の型(VRInitializeException や InvalidOperationException など)
メッセージ全文
ログの先頭の語(OpenVRの初期化に失敗しました、描画エラー など)

控えたら、次の表で当たる節を探します。

出ているもの	進む先
起動の直後に `VRInitializeException` が出て、アプリが終わる	起動で例外が出る: SteamVR または HMD につながらない
起動時に警告が出るが、オーバーレイは表示される	起動で警告が出るが、表示はされる
動いていたアプリが、ログを出して終わる	動いていたアプリが途中で止まる
`ArgumentOutOfRangeException`、`TypeInitializationException`、`FormatException`	渡した値が不正だと言われる
`InvalidOperationException`(`…が祖先に見つかりません`)	ウィンドウやサービスが祖先に見つからないと言われる

AI に貼って聞くときは、メッセージ全文に加えて、FloatSoda のバージョンと、動かした窓の種類(DashboardWindow など)を添えると、原因を絞りやすくなります。

エラーが出ずに動かないときは、このページではなく反応しないときに切り分けるとレイアウトの考え方を読んでください。

起動で例外が出る: SteamVR または HMD につながらない

起動の直後に VRInitializeException が出るのは、OpenVR(SteamVR の API)の初期化に失敗したときです。例外のメッセージの末尾の丸かっこに、失敗の種類が入ります。コンソールには、次のようなログも出ます。

OpenVRの初期化に失敗しました: HMDが見つからないか、接続されていません。 (Init_HmdNotFound)

メッセージの文言は、実行環境の言語(UI カルチャ)で日本語と英語が切り替わります。末尾の丸かっこにある名前(Init_、Driver_、IPC_、Compositor_ などで始まる)は、言語によらず同じです。主な失敗の種類は次のとおりです。

末尾の名前	メッセージ(日本語)	原因と直し方
`Init_HmdNotFound`	HMDが見つからないか、接続されていません。	HMD を PC に接続し、SteamVR に HMD が認識されていることを確かめてから、起動し直す
`Init_InstallationNotFound`	OpenVRのインストールが見つかりません。	SteamVR をインストールする
`Init_VRClientDLLNotFound`	vrclient.dllが見つかりません。	SteamVR のインストール状態を確かめ、壊れていれば再インストールする

--desktop でデスクトップの窓に表示する場合でも、HMD の接続と SteamVR の起動は必要です。HMD を接続していない PC では、Init_HmdNotFound で起動に失敗します(追跡: #140)。この制約は、アプリの起動に関するものです。HMD を接続した PC で、HMD を被らずに画面を確かめる方法は HMD を被らずに確かめるにあります。

SteamVR を先に起動してから、アプリを起動し直してください。

できた? アプリが起動し、ダッシュボードにオーバーレイが出る。

できなかったら

上の表にない失敗の種類が出たときは、末尾の名前とメッセージ全文を控えて、それでも直らないときへ進みます。SteamVR 自体が壊れている場合は、FloatSoda の外の問題です。直し方はこのページに書かず、SteamVR の公式の資料を参照してください。

起動で警告が出るが、表示はされる

次の 2 つの警告は、出ても起動が続き、オーバーレイは表示されます。

ログ	動かなくなる機能	直すかどうか
`SteamVRへのアプリケーション識別に失敗しました: …`	SteamVR への自動起動の登録など、アプリのマニフェストに関わる機能	その機能を使う場合だけ直す
`アクション入力の初期化に失敗しました: …`	コントローラーのボタンやスティックの入力	コントローラー入力を使う場合だけ直す

1 つ目は、SteamVR がアプリを識別できないときに出ます。主な原因は、AppKey が SteamVR に登録されていないことです。警告の後ろに出るメッセージで、原因を確かめます。自動起動を使う場合は SteamVR と一緒に起動するの手順でマニフェストを登録します。2 つ目は、アクション入力の初期化で入力まわりの例外が出たときに出ます。バインディングの問題が候補です。確かめ方はコントローラーの入力を受け取るにあります。

できた? 警告の意味が分かり、自分が使う機能に関わるかどうかを判断できた。

動いていたアプリが途中で止まる

次のログを出してアプリが終わったときは、メインループの中で例外が出ています。例外が出るとログを出してループが止まり、アプリが終了します。ログの先頭の語で、どこで起きたかが分かります。

ログの先頭の語	起きた場所
`タスクエラー`	メインループに積まれた処理
`イベント処理エラー`	SteamVR のイベントとコントローラー入力の処理
`描画エラー`	ウィジェットの作り直しとレイアウト、描画

ログの続きに、例外の型、メッセージ、スタックトレースが出ます。スタックトレースを上から読み、自分のコードのファイル名が出てくる最初の行を探します。その行は、例外につながった呼び出し位置の候補です。例外のメッセージと、その行から呼んでいる処理を合わせて確かめます。FloatSoda. で始まる行しかないときは、自分のコードの呼び出しが原因とは限りません。

できた? 自分のコードのどの部分で例外が出たか分かる。

できなかったら

自分のコードの行が見つからないときは、メッセージ全文とスタックトレースを控えて、それでも直らないときへ進みます。

渡した値が不正だと言われる

設定や入力に許されない値を渡すと、次の例外が出ます。

例外	原因	直し方
`ArgumentOutOfRangeException`(`TargetFrameRateは1以上である必要があります。`)	`FloatSodaOptions.TargetFrameRate` が 0 以下	1 以上の値にする。既定は 60
`TypeInitializationException`(`InnerException` が `NotSupportedException`: `InputAction<…> は未対応です。bool / float / Vector2 を使用してください。`)	`InputAction<T>` の `T` が対応外	`T` を `bool`、`float`、`Vector2` のどれかにする
`FormatException`	`with` 式で `AppKey` の `Value` に、空の値か使えない文字を含む値を入れた(`new AppKey("...")` の時点では検証されない)	小文字の英字、数字、ドット、アンダースコアだけで書く
`ArgumentOutOfRangeException`(`AppKey` の値)	`with` 式で `AppKey` の `Value` に 128 文字以上の値を入れた(`new AppKey("...")` の時点では検証されない)	127 文字以下にする

builder.Services.AddFloatSoda(new FloatSodaOptions
{
    AppKey = new AppKey("example.my_overlay"),
    TargetFrameRate = 60,
});

できた? 例外が出なくなる。

ウィンドウやサービスが祖先に見つからないと言われる

InvalidOperationException で「…が祖先に見つかりません」と言われるのは、探しているウィジェットが、画面の上位にないときです。メッセージと原因の対応は次のとおりです。

メッセージ	原因	直し方
`WindowWidgetが祖先に見つかりません。`	`WindowWidget.Of(context)` を、ウィンドウに包まれていない場所で呼んだ	`CreateWindow` に渡したウィンドウ(`DashboardWindow` など)の子孫のウィジェットで呼ぶ
`ServiceScopeが祖先に見つかりません。`	`context.GetRequiredService<T>()` を、`ServiceProvider` に包まれていない場所で呼んだ	画面のルートを `ServiceProvider` で包む

登録していないサービスを GetRequiredService<T>() で取り出したときも、InvalidOperationException になります。この場合は、builder.Services にそのサービスを登録します。包み方と登録の手順は Generic Host の仕組みを使うにあります。

できた? 例外が出なくなる。

それでも直らないとき

直らないときの行き先は、ガイドの docs で見つからないときにあります。聞くときは、次の情報を添えてください。

メッセージ全文(例外の型とスタックトレースを含む)
FloatSoda のバージョン
動かした窓の種類
再現する手順またはコード