Troubleshooting & Support

StacksAtlas is designed to be a "Zero-Touch" appliance, but network environments can be complex. This guide helps you resolve common connectivity issues and provide diagnostic data if you need to contact support.

1. Finding Your Logs

If the application is behaving unexpectedly, the logs are the first place to look. StacksAtlas utilizes rolling logs stored locally on your Windows machine.

• Log Path: C:\ProgramData\StacksAtlas\logs
• Format: log-YYYYMMDD.txt
• Retention: By default, we keep the last 30 days of logs.

2. Firewall & Antivirus

As a network scanner and web service, StacksAtlas requires specific permissions to function correctly.

Network Ports

• Port 5001 (TCP): The primary API and Dashboard port. This must be open on the host machine's firewall for remote access.
• ICMP (Ping): Essential for basic device discovery.
• ARP (Layer 2): Used for MAC address resolution on the local subnet.

Antivirus Whitelisting

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

• Whitelist the Service: StacksAtlas.API.exe
• Whitelist the Directory: C:\Program Files\StacksAtlas (or your custom install path).

3. Dependency Troubleshooting

StacksAtlas relies on two optional but highly recommended drivers for "Deep Scanning" features.

Npcap Issues

• Symtom: Pings work, but vendor names or OS versions are missing.
• Fix: Ensure Npcap is installed with "WinPcap API-compatible mode" enabled. If you skipped this during install, you must reinstall Npcap.

Nmap Binaries

• Symptom: "Deep Scan" button is disabled or fails immediately.
• Fix: Verify that Nmap is installed and the nmap.exe is in your system PATH, or provide the path in the StacksAtlas settings.

4. Common Status Codes

While using the Dashboard or API, you may encounter specific HTTP status codes.

• 401 Unauthorized: Your session has expired. Please log out and log back in.
• 403 Forbidden: You do not have the required permissions (RBAC) to perform this action (e.g., trying to run a Scan as a "Viewer").
• 500 Internal Server Error: An unexpected error occurred. Please check the Logs (C:\ProgramData\StacksAtlas\logs) for the full stack trace.
• 503 Service Unavailable: The StacksAtlas background service is likely stopped. Check the Windows Services manager (services.msc) to ensure the "StacksAtlas API" is running.

5. Performance Tuning

If you are running StacksAtlas on a lower-spec machine or monitoring a massive subnet, you can tune the engine:

• Polling Interval: Increase this (e.g., to 300s) in the Settings to reduce CPU impact.
• Batch Size: StacksAtlas automatically throttles scan batches to prevent network saturation.
• Database Compaction: The database (stacksatlas.db) can grow over time. The application performs auto-vacuuming, but a manual "Compact" can be triggered from the Maintenance menu.

6. Layer-3 Discovery (Remote Subnets)

When scanning subnets that are not on the local physical interface (e.g., across a router or via VPN), StacksAtlas uses Layer-3 Discovery.

Missing MAC Addresses or Vendor Info

If you see devices with Unknown vendors and missing MAC addresses, it is likely because the device is on a remote subnet. ARP resolution (which provides MAC addresses) does not cross Layer-3 boundaries (routers).

• Fix: To get MAC addresses for these devices, you must install a StacksAtlas appliance directly on that VLAN/Subnet or ensure your network gear supports ARP Proxy/Mirroring (Advanced).

Wake-on-LAN Failures

Magic Packets used for Wake-on-LAN are broadcast packets that typically do not leave the local subnet.

• Fix: Configure your router for Directed Broadcasts (Warning: Security Risk) or use a local StacksAtlas instance to send the packet.

Security Hygiene Limitations

Identification heuristics rely heavily on MAC addresses for vendor lookups. On remote subnets, StacksAtlas relies on Service Fingerprinting (Nmap/mDNS). Ensure Deep Scan is enabled for these devices to improve identification accuracy.

7. 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. OS Version: (e.g., Windows Server 2022)
2. Network Type: (e.g., Flat VLAN, Multiple Subnets)
3. The specific Log File: From C:\ProgramData\StacksAtlas\logs