Skip to content
SuperAlign Surface
Esc
↑↓navigate↵open⌘Jpreview
On this page

Troubleshooting

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.

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 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
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
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
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.

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

Was this page helpful?