Troubleshooting - volcmen/forza-motorsport-linux GitHub Wiki
Home · Install · Play · Recovery
Start with the check for your situation. Run setup commands from the checkout used for installation:
# Composed v0.3 preview:
./setup composed status
# Legacy bootstrap incomplete, interrupted, or not yet installed:
./setup bootstrap --check
# Inspect an installed runtime transaction and readiness:
./setup status
# Direct read-only diagnostics, if installed:
~/.local/bin/forza-doctor
FAIL means a required item is missing or cannot be trusted. A controller or
mountmgr WARN means the exact reviewed original was found; in the manual
workflow it can be considered for the known-build fallback.
A FAIL in that check is not permission to patch an unknown build.
Find the symptom
| Symptom | Next step |
|---|---|
| Fresh bootstrap says the stock Proton base is incomplete | The v0.2 download lacks required custom Wine core fixes. See installation status and #7. Do not bypass the artifact or patch hashes. |
| SteamOS login app or overlay cannot load | The old native GUI tools lack required libraries on SteamOS. The v0.3 preview supplies a pinned Flatpak app/runtime; follow Install. Keep the OS read-only. |
| Preview rejects the Flatpak app, runtime or overrides | Compare the installed commits and permissions with the release manifest. A different runtime needs requalification. Do not downgrade shared runtimes, override the check, or grant broad home/session-bus access. |
| Overlay stops communicating after a game restart | Close and reopen the Flatpak while the new game/service session is active. Its socket bind mount retains the previous inode until restart. |
| Fingerprint mismatch after Steam launched or Finish changed the tool | Preserve the tool and transaction records. #8 remains open; do not delete the journal, ignore executable files in the fingerprint, or accept a newly computed hash as trusted. |
| Hang at the first splash screen after manually copying DLLs | Check for case-insensitive duplicate DLL names in the game directory. A contributor's resolved case had both XGameRuntime.dll and xgameruntime.dll. The read-only ./setup platform-check detects such collisions. Preserve both files and compare them with the installation manifest before correcting anything. This is one observed cause, not a diagnosis for every hang. |
| Bootstrap stopped at a Steam or DLL checkpoint | Complete the printed action, then resume from the same checkout and inputs. See Install. |
| Flatpak Steam or game in another library | Flatpak Steam is unsupported. The composed preview supports one unambiguous additional native library; the legacy bootstrap targets only the primary library. |
| Native library missing | Check the required host libraries; bootstrap does not install packages. |
| AP702 HDD/SSD rejection | The composed tool already includes the reviewed storage change. For a legacy manual setup, inspect the exact-build mountmgr fallback. Do not patch the composed tool or add an SSD launch flag. |
| Controller works elsewhere but not in Forza | Check Steam Input is disabled and the reviewed build is selected. For a manual setup, inspect the controller fallback. |
| Secret Service or credential-store failure | Ensure KDE Wallet exposes org.freedesktop.secrets or has an activatable KDE provider in your user D-Bus session. For the preview's post-reboot ServiceUnknown failure, use the tested activation workaround. Do not add a competing keyring daemon. |
| Xodus service refuses a direct start | Expected: the service requires a launcher ownership token. Use the generated Steam launch options. |
| Socket readiness timeout | Inspect the user journal locally and confirm you used the generated Steam line. Do not enable a permanent Xodus service. |
| No incoming invite notification | Unsupported. Open the explicit Xbox picker; see Invite or join. |
prepared, installing, rolling_back, or recovery_required |
Keep the game closed, preserve all records, and follow Recovery. |
| Uninstall preserves a modified file | Expected: it only removes files proven by its manifest. Review the retained file yourself. |
Protocol errors and rejected experiments
Unimplemented followed by early EOF can indicate mixed XGameRuntime and Xodus
protocol generations. Restore the matching reviewed pair; do not combine the
legacy runtime with newer Xodus.
0x800401f0 and a missing ClientId were investigated in the newer experimental
line. Source fixes for those errors did not make that pair usable in-game.
The newer pair remains rejected live. Do not
switch to it as a troubleshooting shortcut.
Gather a useful report
For local service diagnostics:
journalctl --user -u xodus-forza.service -b --no-pager
Report your release, distribution, native/Flatpak Steam, game-library location, selected Proton tool, failing step, and the relevant doctor result. Say which parts of the game checklist you actually tried.
Read excerpts before sharing. Remove account identifiers, gamertags, XUIDs, authorization data, proof keys, invite/activation data, and private paths. Never attach the licensed DLL or credential store. The tools do not upload runtime logs.
For native Steam layout and SteamOS prerequisite checks, current main also has
./setup platform-check --json. Its output omits private library paths and never
claims Steam Deck gameplay. The composed preview also validates an unambiguous
additional-library layout before making changes; the legacy installer does not.