Troubleshooting

Start here when something does not match the installation or getting started guides. Most issues are wrong URL/port, host firewall rules, Docker network mode, or running portable when you expected Business (or the reverse).

Quick fixes

Symptom	Likely cause	What to try
Browser cannot open the dashboard	Wrong port or host firewall	Windows/Docker: `http://127.0.0.1:5000`. macOS: `http://127.0.0.1:5050`. From another PC on the LAN, open host firewall ports 5000/5001 (see Docker LAN access).
Certificate warning on HTTPS	Local CA not trusted yet	Use HTTP on first launch, or complete the TLS trust step in onboarding. Download the CA from Settings if needed. See security docs.
401 on API calls / logged out constantly	Expired JWT session	Log out and log back in. SSO users: complete login through your IdP again.
Too many login attempts	Auth rate limit (20 / 15 min per IP)	Wait 15 minutes or retry from a different client IP. Applies to login, setup, and portable-session endpoints.
0 devices or wrong device count	Wrong subnet, bridge Docker network, or Layer-3-only path	Confirm the adapter and subnet in Settings. Docker: use `network_mode: host`. Remote VLANs may not show MAC addresses (see Layer-3).
Pings work, no MAC or vendor names (Windows)	Npcap missing or wrong mode	Install Npcap with WinPcap API-compatible mode, or install Nmap (includes Npcap). Not bundled. Optional Deep Scan.
Deep Scan disabled / Nmap unavailable	Nmap not installed (expected on default Docker image)	Discovery still works. Dismiss the banner with Discovery is enough, or add Nmap per installation guide.
License activate returns 401	Post-onboarding requires Admin login	Log in as Admin, then activate in Settings. Portable mode does not need a key.
Node missing from Hub fleet	Enrollment, Tailscale, or sync delay	Hub & fleet guide

1. Logs and debug mode

For the full SYSTEM TERMINAL UI (live stream, Hub/Node dropdown, tail, export, fullscreen), see the System Terminal & Logs guide.

Log file locations

Daily rolling text files: log-YYYYMMDD.txt.

Platform	Path
Windows (MSI / service)	`C:\ProgramData\StacksAtlas\logs`
Windows portable	`%LOCALAPPDATA%\StacksAtlas\logs`
macOS Install (Business)	`/Library/Application Support/StacksAtlas/logs`
macOS portable	`~/StacksAtlas-Trial/logs` (session data)
Docker	Host volume, e.g. `/opt/stacksatlas/data/logs`, or `docker logs stacksatlas`

When contacting us by email, attach the log file for the day the problem occurred and note your version from Settings or GET /api/system/version.

Debug mode (verbose discovery logging)

Available since v1.2.6 on the Logs page (DEBUG MODE / NODE DEBUG toggle). See System Terminal & Logs for all log UI controls.

What it does: Verbose logging with phase timings for mDNS, ARP sweeps, and service enrichment.
When to use it: A device shows offline but responds to ping manually, or counts look wrong after a sweep.
Ghost protection: If more than ~85% of a subnet reports online in one cycle, the engine re-verifies hosts. Debug logs show when that runs.
No restart: Toggle applies to the running engine immediately.

HTTP status codes in the UI

Code	Meaning	Action
401	Session expired or not logged in	Log out and log back in (portable eval uses loopback portable-session).
403	RBAC denied	Admin role required for settings mutations, federation commands, and network settings.
500	Unhandled server error	Check logs for the same day.
503	API process not running	Start the Windows service, Mac menu app/daemon, or Docker container.

2. Windows

SmartScreen or browser blocked the download

New builds can trigger warnings before reputation accumulates. Use Keep in the browser, then More info → Run anyway on SmartScreen. MSI builds are Authenticode-signed from releases.stacksatlas.com. See the FAQ entry on Windows SmartScreen.

Antivirus / EDR false positives

Discovery opens sockets similar to port scanners. Whitelist StacksAtlas.API.exe and C:\Program Files\StacksAtlas (or your portable EXE path) in CrowdStrike, SentinelOne, or similar.

Npcap and missing vendor data

If ping works but MAC addresses or vendor names are empty:

Install Npcap or the Nmap Windows package.
Enable WinPcap API-compatible mode during Npcap setup.
Restart the StacksAtlas service or portable app.

Npcap is not bundled with StacksAtlas.

Service will not start

Confirm StacksAtlas service is set to Automatic and running (services.msc).
Check C:\ProgramData\StacksAtlas\logs for startup exceptions.
After MSI upgrade, reboot if the installer requested it.

3. macOS

macOS won’t open the app

Official DMGs are Developer ID signed and notarized (v1.7.6+). You should not see “unidentified developer” when opening StacksAtlas.app from a current build.

If launch is still blocked (rare download quarantine), right-click StacksAtlas.app → Open once.

Portable: Run StacksAtlas.app from the mounted DMG, not Install StacksAtlas.app, unless you want the Business daemon.

Business: Run Install StacksAtlas.app from the DMG, then open StacksAtlas Menu from the menu bar if the browser does not open automatically.

Firewall blocks the dashboard

Symptom: http://127.0.0.1:5050 (macOS HTTP) or HTTPS on 5001 does not load.

System Settings → Network → Firewall → Options
Allow StacksAtlas.API (or the menu bar helper) for incoming connections.
Homelab tip: the first LAN access attempt often triggers the macOS prompt. Allow it on the Mac host, not only on your Windows admin PC.

Discovery finds 0 devices

Confirm the Mac has permission to use the active network interface (Wi‑Fi or Ethernet).
Business daemon runs with the privileges installed by Install StacksAtlas.app; you should not need manual sudo for normal use.
Check logs under /Library/Application Support/StacksAtlas/logs or portable ~/StacksAtlas-Trial/logs.

4. Docker (Linux / NAS)

Cannot open the UI from another machine on the LAN

curl http://127.0.0.1:5000/api/health works on the host, but http://<node-ip>:5000 times out from your laptop: the appliance is listening, but the host firewall blocks inbound traffic.

sudo ufw allow 5000/tcp
sudo ufw allow 5001/tcp

Verify remotely: curl http://<node-ip>:5000/api/health should return 200.

Ghost ping / wrong device counts (bridge network)

Cause: Default Docker bridge mode isolates the container from Layer-2 ARP on your LAN.

Fix: Use network_mode: host in docker-compose.yml (see repo examples). Add NET_ADMIN and NET_RAW if your compose file includes them for discovery.

Deep Scan unavailable in Docker

The default image does not include Nmap. Subnet discovery, security grades, and reports still work.

Symptom: Dashboard notice about Deep Scan, button disabled, or Settings → Scanning shows Nmap unavailable.
OK without it: Click Discovery is enough on the notice.
Need port-level scan: Optional Deep Scan (local Dockerfile on the NAS, no source checkout required).

Data gone after container restart

Map a host directory to /app/data, for example:

volumes:
  - /opt/stacksatlas/data:/app/data

Portable compose: use docker compose -f docker-compose.portable.yml down -v only when you intend to wipe session data.

Portable vs Business container on the same host

Only one appliance should own the host ports. Stop a stacksatlas-portable test container before starting the Business stacksatlas service (or the reverse).

5. Licensing and activation

Issue	Fix
Activate returns 401 after onboarding	Log in as Admin, then activate in Settings.
Hardware ID mismatch	Deactivate in the Lemon Squeezy portal, then activate on the new machine.
Grace period warnings	Business needs occasional online validation; portable does not use license keys.
Missing alerts or federation	Confirm Business license is active. Portable is session-only.

Details: Getting started and Legal hub.

6. Hub and fleet (Business)

Issue	Fix
Node never appears on Hub	Finish enrollment on the Node; verify federation token and Hub URL.
Remote Node shows offline	Confirm Node is running and can reach Hub :5001/:5002 (Node initiates outbound). Check Tailscale/LAN routing and Windows Hub firewall for TCP 5002.
Command or setting returns 403	Admin role required on the Hub for federation mutations.
Deleted device reappears on Hub	Use Remove from Fleet (tombstone). See federation guide.

7. Layer-3 and remote subnets

Scanning across a router, VPN, or VLAN without a local Node uses Layer-3 discovery (ICMP/TCP only).

Missing MAC / vendor on remote subnets: ARP does not cross routers. Expected.
Fix: Deploy a Node on that VLAN, or use Deep Scan (with Nmap installed) for protocol-level fingerprinting on reachable IPs.

8. Still stuck?

Installation (portable vs MSI/Mac/Docker)
Getting started (onboarding and license)
FAQ on the home page
Integrations (webhooks, API 401s)

Business customers: use the Lemon Squeezy customer portal from your receipt for license moves and billing.

Self-service first: docs and FAQ cover most setup and fleet issues. Email is best-effort for licensing, billing, or problems not answered above.

Read the FAQ · admin@stacksatlas.com

Dashboard

Discovery pipeline