Skip to content
SuperAlign
Surface
SurfaceAI assets on employee endpoints
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 endpoint. 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 endpoint 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 endpoint 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, device is enrolled in another organization The endpoint is already enrolled in a different organization Contact SuperAlign support with the endpoint’s hostname. An endpoint is never moved between organizations on its own, and uninstalling or reinstalling does not release it
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 endpoint 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 endpoint
Tray says Session expired The sign-in on an interactively enrolled endpoint 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
Every asset shows Unknown The policy catalog could not be downloaded Log says scan rules skipped: catalog is empty. Check connectivity. Real scores appear after the next successful scan
One asset shows Unknown, and connectivity is fine No policy covers that kind of asset yet, or the scanner could not check enough of them Nothing to fix. See Which assets 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 an asset they need A Block action reached their endpoint Make an exception for that endpoint. See One asset on one endpoint
Sessions do not appear after turning on session monitoring for an AI tool The endpoint has not scanned yet, or the AI tool is not installed there Wait one scan interval. Run sudo surface extension list on the endpoint; the extension should show as installed
Chrome extension shows disconnected The scanner is not running on that endpoint 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 endpoint’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?