PITWALLOSdocs

Agent troubleshooting

First-pass checklist when a rig isn't responding. Most issues fall into one of these buckets.

Rig is on agent v2.x (multi-title cutover)

As of agent v3.0.0 the heartbeat payload changed shape (we now report engine-agnostic running state). The backend rejects v2.x heartbeats with HTTP 426 Upgrade Requiredso old rigs can't poison the new rig_status columns.

  • Symptom: rig dot stays grey even though the agent is running. The agent log shows 426 on every heartbeat.
  • Fix: download the latest installer from the admin console and re-run it on the rig PC. The installer is in-place — your rig token is preserved and you don't need a setup token.
  • The super-admin venue page lists each rig's reported agent version with below-minimum versions in red — use that to track which PCs still need touching during a venue rollout.

Rig dot is grey

Means: heartbeat not arriving in the last ~75 seconds.

  • Is the rig PC powered on and connected to the network? Tryping pitwallos.com from the PC.
  • Is the PitwallOSAgentservice running? Open Services.msc → look for “PitwallOS Agent”.
  • Outbound HTTPS to *.pitwallos.com blocked? Most office firewalls allow it, but cellular hotspots sometimes throttle.

Rig dot is red

Means: agent connected but the last command failed. Click into the rig in the admin console to see the error.

Common causes:

  • AC isn't installed at the path the agent expects. The agent looks at %PROGRAMFILES(X86)%\Steam\steamapps\common\assettocorsa. If yours is elsewhere, set AC_HOMEin the agent's config file.
  • Missing circuit / vehicle. The admin tried to start a session with content not installed locally. Install it and retry.
  • CSP version mismatch. Pin to 0.2.5-preview1 per the AC config doc.

“Setup token expired or already used”

Setup tokens are one-shot and live for 24 hours. Generate a fresh one from the admin console and re-bind. Existing rigs keep their long-lived rig token regardless.

Re-binding a rig

If you replace a PC or re-image the disk, you can re-bind the new agent to the same logical rig. Use PitwallOSAgent --rebindon the rig PC; it'll prompt for a new setup token. The existing rig in the admin console keeps its history.

rFactor 2 specific issues

rF2 launches go through a different code path than AC (we run a localhost dedicated server and join it from the client) so the failure modes are different too.

“rF2 install_status: missing” on the agent compliance dashboard

The agent couldn't locate rF2 at the configured path. On the rig:

  • Open the agent's setup GUI → Paths → rFactor 2 and confirm both Install dir and UserData dir are set.
  • Both rFactor2.exe and rFactor2 Dedicated.exe must exist inside the install dir. If only one is present, reinstall through Steam.

“rF2 install_status: incompatible”

Either the rF2 client or the rF2 Dedicated Server is missing from this rig. PitwallOS launches solo sessions through a localhost dedicated server, so both must be installed on every rF2-enabled rig.

  • The rF2 client(Steam AppID 365960) installs through the regular Steam client — the operator is expected to do this.
  • The rF2 Dedicated Server (Steam AppID 400300) is installed automatically by the agent on the first heartbeat. Check the rF2 dedi installcolumn on the agent-compliance dashboard to see the current phase — while it is scheduled, downloading_steamcmd, or installing_dedi the rig will show as incompatible until install completes.
  • If the dedi install is in failed state, the dashboard surfaces the SteamCMD error verbatim and exposes a manual Retrybutton. The agent also retries automatically with exponential backoff (5 min, 30 min, 2 hr). See rF2 configuration for details on what the agent does behind the scenes.

Note: the rF2 shared-memory plugin DLL is auto-deployed by the agent on every heartbeat — you no longer need to copy it manually. If you see a separate warning about the plugin being missing, it usually means the rig user account can’t write into the rF2 install dir; re-run the agent as the same user that installed rF2.

rF2 starts then immediately exits to the main menu

Usually means the localhost dedicated server didn't come up in time. Check the agent log for errors from rFactor2 Dedicated.exe — common causes:

  • Port 54297 or 5397 already in use. Kill any stale rFactor2 Dedicated.exefrom Task Manager and retry. The agent also tries graceful shutdown via the dedi REST API on every command, so a clean PitwallOS install shouldn't leak a process — but other rF2 tooling on the same PC can.
  • .rfmod build failed. PitwallOS builds an .rfmod package per circuit+vehicle combo on first launch, then caches it by content fingerprint. Failures surface in the agent log with an rfmod_build_failed error code and the underlying ModMgr stderr. The most common cause is a missing dependency: install whatever .rfcmp the log mentions and retry.
  • Custom Plugin Variables disabled. Without this toggle, rF2 silently refuses to load the PitwallOS plugin — the dedi starts but telemetry never arrives, so the agent times out the join phase.

Launches are refused with “rF2 canary not enabled for this rig”

rF2 is gated behind rigs.pitwall_rf2_enabled during rollout. The rig has rF2 installed and reports install_status=ok, but the platform team hasn't flipped the canary flag on yet. Ask in the PitwallOS support channel; the flag flip is one click on /super-admin/agent-compliance once the rollout team has verified the rig.