Troubleshooting

"SnitchOS first install needs TENANT_ID (UUID) plus a provisioned bootstrap key" on install

Full text: "SnitchOS first install needs TENANT_ID (UUID) plus a provisioned bootstrap key. Use the dashboard's RMM installer script, it writes the enrollment key to the ACL'd bootstrap registry, then runs msiexec with BOOTSTRAP_READY=1."

Opened without a tenant ID or bootstrap key — refused by design. The key never touches a command line: written to an ACL-restricted subkey, gated by non-secret BOOTSTRAP_READY=1.

Fix: sign in at app.snitchos.com → Tenants → <tenant> → Install agents, download Install-SnitchOS-<slug>.ps1, run elevated. One machine: manual install. Own tooling: deployment guide.

The downloaded installer stops without installing

Almost always a renamed file: identity is the SnitchOS_<code>.exe filename, browser suffixes excepted (… (1).exe, … - Copy.exe).

Fix: restore the name, or redownload from Tenants → <customer> → Install agents if it was revoked or expired.

Enrollment returns "Invalid enrollment credentials"

In order of likelihood:

1. Key already used up: a one-off key with max uses = 1 was used before, or an administrator deliberately rotated the fleet key.
2. Key expired: past its expiry date.
3. Key revoked: an admin revoked it in the dashboard.
4. Wrong tenant ID: mistyped UUID in a manual install.

Fix: download a fresh installer or mint a one-off key, then rerun. The message is deliberately identical across causes so it can't be probed.

Enrollment returns "This machine is already enrolled and its agent is using the token it has"

A fresh key won't clear this — already enrolled on its own credentials; enrollment keys add machines, never take over ones reporting.

Seen when credentials are gone: purged state, a restored image, or a hand-deleted registry key. Fix:

1. Open Users and Devices, find the machine in the Devices table, and choose Allow re-enrolment — one re-enrolment within a limited window. The agent picks it up on its next retry; no need to re-run the installer.
2. If the machine was wiped or reimaged, do nothing: it arrives as a new device on its own.
3. If the device was revoked by an admin, reactivate it first — re-enrolment doesn't override a revocation.

A revoked, expired, or used-up key is refused before any of this: replace it first.

Devices enrolled but every user shows as "unknown"

The per-session helper isn't running. Check:

Get-Process SnitchOS.SessionAgent -ErrorAction SilentlyContinue |
    Select-Object Id, SI, ProcessName

SI should be non-zero (interactive session). Fix: if none, collect C:\ProgramData\SnitchOS\logs\agent-*.log and contact us.

Antivirus flags the agent

Security products may flag the input-count hook; SnitchOS records counts only. Fix: verify installer and binaries are signed by the expected publisher, then agree an allow rule with security. Never bypass an unsigned-publisher warning.

Device doesn't appear on the tenant overview

Fix, in order:

1. Wait 60 seconds, first check-in is quick but not instant.
2. Run the local health helper: & "C:\Program Files\SnitchOS\SnitchOS.HealthCheck.ps1", it reports service state and connectivity.
3. Confirm the endpoint can reach api.snitchos.com and cdn.snitchos.com over HTTPS (proxy/firewall rules).

Uninstall left files behind

Normal uninstall keeps local state by design. Fix:

msiexec /x "{<product-code>}" /qn PURGE_CONFIG=1