---
title: Troubleshooting
description: Find what you are seeing, then do the one thing that fixes it.
---

Start with these three commands on the laptop. They answer most questions.

```bash
sudo surface status          # is the service running, which organization
sudo surface scan --once     # run one scan and watch the output
sudo surface logs -n 200     # recent log lines
```

On Windows, run them from an elevated PowerShell without `sudo`.

## What you see, and what to do

| What you see | What it means | Do this |
| --- | --- | --- |
| The laptop never appears on **Endpoints** | It has not enrolled, or cannot reach SuperAlign | Run `sudo surface status`. If the service is not running, run `sudo surface init`. Then check the rows below for the error in the log |
| Log: `provisioning source failed` | The enrollment token did not reach the laptop | Check the MDM setting landed: macOS `defaults read /Library/Managed\ Preferences/com.superalign.surface`, Windows `reg query HKLM\SOFTWARE\Policies\Superalign\Surface`, Linux `cat /etc/surface/managed.conf` |
| Log: `401` on enroll | The token was revoked, expired, or mistyped | Create a new [enrollment token](/surface/admin/enrollment-tokens) and update your MDM |
| Log: `409` on enroll or sync | The laptop is already enrolled in a **different** organization | Delete it from that organization's Endpoints page, then run `sudo surface init` |
| Log: `429` on enroll | Rate limited during a large rollout | Nothing. The scanner retries on the next scan |
| Log: connection refused or timeout to `*.superalign.ai` | A firewall or proxy is blocking the scanner | Allow outbound HTTPS to `*.superalign.ai`. See [Requirements](/surface/deploy/requirements) |
| The laptop shows **Stale** on Endpoints | It stopped reporting | It is switched off, the scanner was removed, or a firewall now blocks it. Run `sudo surface status` on the laptop |
| Tray says **Session expired** | The sign-in on an interactively enrolled laptop ran out | `sudo surface logout`, then `sudo surface init` |
| Log: re-authentication stopped after 3 attempts | Automatic sign-in gave up | `sudo surface init` to sign in by hand |
| A Block or Warn takes up to 15 minutes to arrive | The live channel to the gateway is blocked | Allow WebSocket connections to `*.superalign.ai`. Scanning is unaffected |
| Tools show a dash instead of a score | The policy catalog could not be downloaded | Log says `scan rules skipped: catalog is empty`. Check connectivity. Scores appear after the next successful scan |
| A tool shows a dash, and connectivity is fine | No policy applies to that kind of tool yet | Nothing to fix. See [Which tools get a score](/surface/risk/scoring#which-tools-get-a-score) |
| Installer prints `Run: sudo surface init` | The package installed but the service did not start | Run it. Then `sudo surface status` |
| The desktop app does not open on Linux | The WebKitGTK 4.1 runtime is missing | Install the package with `apt` or `dnf`, not `dpkg -i` or `rpm -i` |
| Tray says the helper was not found | The desktop app was not included in this build | Use the console in a browser. Report it to SuperAlign |
| A person reports a **BLOCKED** notification for a tool they need | A Block decision reached their laptop | Make an exception for that laptop. See [One tool on one laptop](/surface/governance/remediate#one-tool-on-one-laptop) |
| Sessions do not appear after turning on a collector | The laptop has not scanned yet, or the tool is not installed there | Wait one scan interval. Run `sudo surface extension list` on the laptop; the collector should show as installed |
| Chrome extension shows **disconnected** | The scanner is not running on that laptop | `sudo surface status`, then `sudo surface init` if needed |

## Send this to support

Collect the following before you write to SuperAlign support. It usually saves a round trip.

```bash
sudo surface status --json > surface-status.json
sudo surface logs -n 1000 > surface-logs.txt
```

Then include:

- The two files above
- The install log: `/var/log/surface-install.log` (macOS, Linux) or `%ProgramData%\Surface\install.log` (Windows)
- The laptop's hostname and operating system
- Your **Organization ID** from the console's Settings page
- What you expected, what you saw, and when it started

## Related

- [Files, services, and logs](/surface/scanner/files-and-services) for where everything lives on the laptop
- [Scanner commands](/surface/scanner/commands)