Troubleshooting

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

The full text is: "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."

The MSI was opened without a tenant ID and without a provisioned bootstrap key. This is an intentional validation failure. There is no enrollment-key MSI property to supply instead — the key deliberately never touches a command line, so it cannot leak through a process list or a verbose install log. The wrapper script writes it to an ACL-restricted registry subkey and the MSI gates on the non-secret BOOTSTRAP_READY=1 flag.

Fix: sign in at app.snitchos.com → Tenants → <tenant> → Install agents → download Install-SnitchOS-<slug>.ps1 and run it elevated on the endpoint. For a single machine, the downloadable per-customer installer is simpler still — see manual install. The deployment guide shows the underlying sequence if you need to reproduce it in your own tooling.

The downloaded installer stops without installing

Almost always a renamed file — the customer identity in SnitchOS_<code>.exe is the filename. Browser suffixes (… (1).exe, … - Copy.exe) are fine; anything else is not.

Fix: restore the name, or download a fresh copy from Tenants → <customer> → Install agents. If the name is intact, it was revoked or expired — check Downloaded installers there. See manual install.

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.

The error is intentionally identical in all four cases so key/tenant existence can't be probed. Fix: download a fresh installer script (or mint a fresh one-off key) and rerun.

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

A different error with a different fix — a fresh key will not clear it. The machine is already in the dashboard and its agent is actively using the credentials it holds, and an enrollment key is authority to add machines to an organization, not to take over one that is already reporting.

Most repairs never reach this, because the agent proves it is the same machine using the credentials it already had. You will see it when that proof is genuinely gone — the endpoint's local state was purged, the disk was restored from an image, or the credentials were deleted by hand.

1. Open Users and Devices, find the machine in the Devices table, and choose Allow re-enrolment. That permits one re-enrolment within a limited window. The agent picks it up on its next retry — you do not 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. Permitting re-enrolment does not override a revocation.

One overlap with the section above: a revoked, expired or used-up key is refused before any of this is considered, so if the key is also spent, replace it first — permitting re-enrolment cannot get past a spent key.

Devices enrolled but every user shows as "unknown"

The per-session helper isn't running in user sessions. On the endpoint, check:

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

SI should match a non-zero interactive session id. If no process exists, collect C:\ProgramData\SnitchOS\logs\agent-*.log and open a support ticket.

Antivirus flags the agent

Security products can flag the input-count hook even though SnitchOS records counts only. First verify the installer and binaries are signed by the expected publisher. Then work with the client's security team on the narrowest appropriate allow rule. Do not rely on a permanent hash exception because the hash changes with each release, and never bypass an unsigned-publisher warning.

Device doesn't appear on the tenant overview

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

By design, normal uninstall keeps local support state so a reinstall keeps history. To remove everything:

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