PITWALLOSdocs

Agent troubleshooting

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

Rig dot is grey

Means: no heartbeat in the last ~75 seconds. Work through these in order — each takes about 30 seconds.

  1. PC on and online? Try ping pitwallos.com from the rig. Cellular hotspots and captive-portal Wi-Fi sometimes drop long- lived connections.
  2. Scheduled Task running? Open Task Scheduler (taskschd.msc) and expand Task Scheduler Library → PitwallOS. The task named PitwallOS Rig Agent should be Running. If it's Ready, right-click → Run.
  3. Process alive? In Task Manager you should see two pitwallos-agent.exerows — that's normal, it's the PyInstaller bootloader plus its child. Both being missing means the task didn't start.
  4. Outbound HTTPS to *.pitwallos.com blocked?Most office and home networks allow it, but restrictive corporate firewalls sometimes don't. The agent needs outbound HTTPS on port 443 to your venue subdomain and to github.com (installer updates only).
  5. Old agent version? Anything on agent v2.x gets rejected by the backend with 426 Upgrade Required(the heartbeat schema changed at v3.0.0). Download the latest installer from the admin console and run it in-place — your rig token is preserved.

Rig dot is red

Means: the agent is heartbeating but the last command failed. Click into the rig on Sim Control to read the error verbatim. Common causes:

  • Engine not installed at the path the agent expects. Fix on the rig: open the setup GUI (Start menu → PitwallOS Setup) → Engine paths tab, correct the path, save. The agent picks up the change on the next heartbeat.
  • Missing circuit or vehicle. An admin tried to launch a session with content not installed locally. Install the missing car/track on the rig and the agent will re-sync it into the Content library.
  • CSP version mismatch. Custom Shaders Patch must be pinned per the AC config doc; newer previews can break the agent's INI parser.

“Setup token expired or already used”

Setup tokens are one-shot and live for 24 hours. Generate a fresh one from Settings → Rigs & agents and re-paste it into the setup GUI. Rigs already bound to your venue don't need a new token — their long- lived rig tokens keep working forever.

Re-binding a rig after a re-image

If you replace a PC or wipe its disk, the rig's stored token is gone. To adopt the fresh install into your existing rig row (keeping its history intact):

  1. Reinstall the agent using the same installer.
  2. Generate a fresh setup token from the admin console.
  3. On the rig, open the setup GUI → Register rig tab, paste the token, click Bind. The admin console recognises the rig by its hardware fingerprint and reattaches to the existing row.

rFactor 2 specific issues

rF2 launches take a different 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”

The agent couldn't locate rF2 at the configured paths. On the rig, open the setup GUI → Engine paths → rFactor 2 and confirm both Install dir and UserData dir are set and exist on disk. rFactor2.exe should be under <install>/Bin64/; if it's not, reinstall through Steam first.

“rF2 install_status: incompatible”

The rF2 client is present but the rF2 Dedicated Server (App ID 400300) hasn't finished installing yet. PitwallOS needs both because solo launches go through a localhost dedicated server. The agent installs the dedi automatically — check the rF2 dedi install column on the super-admin agent-compliance dashboard for the current phase:

  • scheduled, downloading_steamcmd, installing_dedi— in progress, no action needed. Total time is usually 3-10 minutes.
  • failed— 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).
  • installed — the rig will re-report install_status=ok on the next heartbeat and bookings can route to it.

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 (Start menu → PitwallOS Setup → Log viewer) for errors from rFactor2 Dedicated.exe. Common causes:

  • Port 54297 or 5397 in use. Kill any stale rFactor2 Dedicated.exefrom Task Manager and retry. PitwallOS gracefully shuts the dedi down on every command, so a clean install shouldn't leak — but other rF2 tooling on the same PC can.
  • .rfmod build failed. The agent builds a per-content .rfmod on first launch and caches it. Failures surface with an rfmod_build_failederror and the underlying ModMgr stderr. Most common cause: a missing dependency — install whatever .rfcmp the log mentions and retry.
  • Custom Plugin Variables disabled. The agent re-enables the shared-memory plugin on every launch, but if rF2 auto-disables it after a crash faster than the agent can re-enable it, you can end up in a loop. Fix once by opening rF2 → Options → Plugins and ticking rFactor2SharedMemoryMapPlugin64.

“rF2 canary not enabled for this rig”

rF2 is gated per-rig during rollout via rigs.pitwall_rf2_enabled. The rig has rF2 installed and reports install_status=ok, but the platform team hasn't flipped the canary on yet. Ping the PitwallOS support channel; the flip is one click on /super-admin/agent-complianceonce we've verified the rig.

Reading the agent log

Every agent action writes to a rolling log at %LOCALAPPDATA%\PitwallOS\agent\logs\agent.log. The setup GUI has a Log viewertab that tails it live — the fastest way to see what the agent was doing when something failed. If you're asking for support, screenshot the last few dozen lines around the error and paste them into the ticket.

Getting further help

Nothing above matched? Grab the last 200 lines of agent.logplus the rig's agent version (bottom-right of the setup GUI) and email hello@pitwallos.com. The version + log combo is enough to identify almost every install-time issue.