Troubleshooting & Support

StacksAtlas is designed to be a "Zero-Touch" appliance across all platforms. When complex network environments cause unexpected behavior, consult this guide to resolve common connectivity issues or gather diagnostic data before contacting support.

1. General Troubleshooting (All Platforms)

Finding Your Logs

If the application is behaving unexpectedly, the logs are the first place to look. Logs are stored as daily rolling text files (log-YYYYMMDD.txt).

• Windows: C:\ProgramData\StacksAtlas\logs
• macOS: /Library/Application Support/StacksAtlas/logs
• Docker: Check your volume mount (e.g., /opt/stacksatlas/data/logs) or use docker logs stacksatlas.

Common Status Codes

If you encounter errors in the Dashboard UI:

• 401 Unauthorized: Your session expired. Log out and log back in.
• 403 Forbidden: You lack the required RBAC permissions for the action.
• 500 Internal Server Error: An unexpected engine failure. Please review your logs.
• 503 Service Unavailable: The background daemon or Docker container has stopped. Ensure the service is running.

2. Windows Troubleshooting

Antivirus Whitelisting

Because StacksAtlas performs "Service Fingerprinting" (similar to Nmap), aggressive EDR/Antivirus platforms (CrowdStrike, SentinelOne) may flag the service.

• Whitelist the Service: StacksAtlas.API.exe
• Whitelist the Directory: C:\Program Files\StacksAtlas

Npcap Issues (Missing Vendor Data)

If device pings succeed but MAC addresses, vendor names, or OS versions are missing:

• Fix: Ensure Npcap was installed with "WinPcap API-compatible mode" enabled. If you skipped this during the MSI installation, uninstall Npcap via Windows Settings and reinstall it from C:\Program Files\StacksAtlas\dependencies.

3. macOS Troubleshooting

Daemon Permission Errors

StacksAtlas must use low-level APIs (libpcap) to intercept raw network traffic for discovery.

• Symptoms: Discovery engine fails to start, or 0 devices are found.
• Fix: You must launch the binary with administrative privileges. Ensure you are running it via sudo ./StacksAtlas.API from the terminal.

macOS Firewall Blocks

If you cannot load the dashboard in your browser (https://localhost:5001), the native macOS firewall may be blocking the process.

• Fix: Go to System Settings > Network > Firewall > Options and ensure StacksAtlas.API is set to "Allow incoming connections".

4. Docker Troubleshooting (Linux / NAS)

The "Ghost Ping" Problem

If you are running the Docker container and notice inaccurate device counts, duplicate IPs, or missing MAC addresses, your container network is misconfigured.

• The Cause: Running the container in default bridge mode isolates it from the physical Layer-2 network.
• The Fix: You must deploy the container using --network host. This is a strict requirement for the Nmap Discovery Engine to perform raw ARP resolution.

Persistent Data Loss

If you restart your container and lose your configuration, license, or historical data:

• The Fix: Ensure you mapped a physical directory on your host to the container's /app/data volume (e.g., -v /opt/stacksatlas/data:/app/data).

5. Layer-3 Discovery (Remote Subnets)

When scanning subnets not physically connected to the host's network interface (e.g., across a router, VLAN, or VPN), StacksAtlas uses Layer-3 Discovery.

Missing MAC Addresses

If devices on remote VLANs show Unknown vendors and no MAC addresses, this is a standard limitation of Layer-3 networking. ARP packets do not cross routers.

• Fix: Install a StacksAtlas appliance directly on that VLAN, or rely on enabling the Deep Scan feature so StacksAtlas can fingerprint the device using higher-level protocols (HTTP/SSH/mDNS).

6. Getting Expert Support

If you've checked the logs and firewall but still need help, our founder is available for direct support.

Please provide the following context in your email:

1. Platform: (Windows, macOS Intel, macOS Silicon, or Docker/Linux)
2. Network Setup: (e.g., Flat VLAN, Multiple Subnets)
3. The specific Log File