Troubleshooting

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.
Readiness reports native GTK/WebKit/SDL missing for the preview	Use the current read-only diagnostic; its default composed profile checks the native service and Flatpak prerequisites. The tagged diagnostic predates this correction.
Doctor reports low space despite a separate game disk	Current Doctor checks the recorded game directory for composed installs and steamapps for legacy bind mounts. For existing installs, run ./setup platform-check --profile legacy from a current diagnostic checkout to inspect the actual game filesystem; preserve managed installed scripts and recovery records.
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. It defaults to composed-preview prerequisites; use --profile legacy for native v0.2 prerequisites. 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.

Open a project issue