Scanning Issues

Issues triggered by running scans, including network load, missing hosts, and scan performance.

Port Scanning Slows Down or Crashes Target Hosts

Symptoms: Web interfaces on target hosts become unresponsive during scans; network feels slow; IoT devices or services with small listen backlogs (e.g. Pi-hole) stop responding; services require restart after scan.

Cause: The default port scan rate (500 pps) and batch size (200 ports) can overwhelm hosts with small TCP listen queues, especially on low-latency networks (e.g. LXC containers on the same Proxmox host).

Solutions:

Reduce scan_rate_pps and/or port_scan_batch_size in your daemon configuration:

# CLI
scanopy-daemon --scan-rate-pps 100 --port-scan-batch-size 100

# Environment variables
export SCANOPY_SCAN_RATE_PPS=100
export SCANOPY_PORT_SCAN_BATCH_SIZE=100

# Docker
environment:
  - SCANOPY_SCAN_RATE_PPS=100
  - SCANOPY_PORT_SCAN_BATCH_SIZE=100

Recommended values:

See Daemon Configuration for the full parameter reference.

Hosts Not Discovered / Missing IPs

Symptoms: Discovery completes but some known hosts are missing from results.

Most likely causes:

• The host is not responding to ARP — it's on a different subnet, asleep, filtering ARP, or on an overlay network.
• Switch rate limiting (DAI) — the switch is dropping ARP packets before they reach hosts or before responses return.

To tell them apart, run arping -c 3 <missing-ip> from the scanner host. If arping also fails, the host is unreachable at Layer 2 — see Hosts Not Responding to ARP. If arping succeeds but Scanopy misses the host, the issue is likely rate limiting — see Switch Rate Limiting (DAI).

Hosts Not Responding to ARP

These issues are independent of Scanopy — the host is genuinely unreachable via Layer 2 ARP from the scanner's network segment. Manual arping will also fail.

Host is on a different subnet or behind a router

ARP is Layer 2 only. Hosts on other subnets won't see broadcast ARP requests from the scanner's VLAN — routers don't forward ARP broadcasts.

Solution: Run a scanner daemon on each subnet, or add the remote subnet as a target so the daemon's routed-ping fallback can reach it.

Host is asleep or in low-power mode

Laptops, IoT devices, and phones in sleep or Wi-Fi power-save mode may not respond to ARP promptly or at all.

Solution: Increase arp_retries to give sleeping hosts more chances to wake and respond. Schedule scans during active hours. Accept that sleeping devices will appear intermittently.

Host has static ARP or ARP filtering enabled

Some hardened hosts or embedded devices ignore broadcast ARP or only reply to unicast ARP for known peers.

Solution: Increase arp_retries (unicast retries may succeed where broadcast failed). Verify with arping -c 3 <ip> from the scanner host — if that also fails, the host is filtering ARP.

Virtual machines or containers with restricted networking

VMs in NAT mode or containers on an overlay network are not reachable via Layer 2 ARP on the physical segment.

Solution: Scan from within the virtual network, or switch the VM/container to bridged networking so it appears on the physical segment.

Switch Rate Limiting (DAI)

Understanding ARP Scanning

Scanopy uses broadcast ARP for fast host discovery. For each target IP, we send an ARP "who-has" request and wait for a reply. This is faster and more reliable than TCP/UDP probing because hosts cannot firewall ARP and still communicate on the network.

However, many managed switches implement Dynamic ARP Inspection (DAI) to prevent ARP spoofing attacks. DAI rate-limits ARP packets on untrusted ports to a maximum number of packets per second (pps). When the limit is exceeded, the switch either drops excess packets silently or disables the port entirely.

Known default rate limits:

If your switch has DAI enabled and Scanopy sends ARP faster than the limit allows, excess packets are dropped and those hosts appear offline.

How Retries Work

Scanopy uses targeted retries rather than simple broadcast flooding:

1. Round 1: Send ARP request to all target IPs at the configured rate
2. Wait: Collect responses for 3 seconds
3. Round 2: Send ARP requests only to IPs that didn't respond
4. Repeat: Continue for the configured number of retry rounds
5. Final wait: Extra collection period for late-arriving responses

This approach minimizes total packets sent (only non-responders are retried) while giving slow or rate-limited hosts multiple chances to be discovered.

Example with arp_retries=2 (default) scanning a /24:

If rate limiting caused packet loss in round 1, rounds 2 and 3 retry only those hosts—often successfully since the burst is smaller.

Diagnosis

1. Check if your switch has DAI enabled. Consult your switch documentation for how to view DAI configuration and statistics. Look for rate limit violations or dropped ARP packets.

2. Check for port shutdown. Some switches (notably Cisco) disable the port entirely when the rate limit is exceeded. If your scanner lost network connectivity during a scan, this is likely the cause.

3. Test with manual arping:

   arping -c 3 <missing-ip>

   If arping finds the host but Scanopy doesn't, rate limiting is likely the cause. If arping also fails, the host is unreachable at Layer 2 — see Hosts Not Responding to ARP above.

Solutions

Option 1: Reduce ARP scan rate

Lower arp_rate_pps to stay within your switch's DAI limit:

# CLI
scanopy-daemon --arp-rate-pps 15

# Environment variable
export SCANOPY_ARP_RATE_PPS=15

# Docker
environment:
  - SCANOPY_ARP_RATE_PPS=15

Recommended values:

Option 2: Increase retries

If rate limiting causes occasional packet loss, more retries give hosts additional chances to respond:

# CLI
scanopy-daemon --arp-retries 4   # 5 total rounds (default is 2 = 3 rounds)

# Environment variable
export SCANOPY_ARP_RETRIES=4

Higher retries help when:

• Rate limiting drops some packets but not all
• Hosts are slow to respond (busy or sleeping devices)
• Network has high background traffic

The tradeoff is longer scan time, but since retries only target non-responders, the overhead is usually small.

Option 3: Adjust your switch DAI configuration

If you control the switch, you can increase the rate limit on the scanner's port or mark it as trusted (no rate limit). Consult your switch documentation for the specific commands.

Option 4: Use Npcap for broadcast ARP (Windows only)

On Windows, Scanopy defaults to the SendARP API which scans hosts sequentially. For faster scanning, you can enable Npcap broadcast ARP:

# CLI
scanopy-daemon --use-npcap-arp

# Environment variable
export SCANOPY_USE_NPCAP_ARP=true

# Docker
environment:
  - SCANOPY_USE_NPCAP_ARP=true

Requirements:

• Npcap must be installed (free for personal use)
• During Npcap installation, enable "WinPcap API-compatible Mode"

When to use Npcap:

• Scanning large subnets where sequential SendARP is too slow
• You need the same broadcast ARP behavior as Linux/macOS

When to stick with SendARP (default):

• Npcap is not installed or cannot be installed
• Scanning small networks where speed doesn't matter
• You want zero additional dependencies

Tuning for Your Network

See Daemon Configuration for all ARP settings.

Discovery Takes Hours

Symptoms: Network discovery takes hours to complete.

Most likely cause: You're scanning a large subnet the daemon isn't directly connected to. Without Layer 2 adjacency, ARP-based discovery is unavailable and the daemon falls back to slower TCP probing — scanning each IP individually.

Solutions:

1. Remove or shrink oversized subnets: Check your target list for /16s or larger subnets. Only scan subnets that actually contain hosts you care about.

2. Use Docker discovery for Docker networks: The default Docker bridge network (172.17.0.0/16) is 65,536 IPs and the daemon has no L2 path to it. Use Docker discovery instead — it queries the Docker API directly and takes seconds.

3. Deploy a daemon on the target segment: If the daemon reaches a subnet only via a gateway, ARP is unavailable and discovery falls back to TCP probing. Deploy a daemon on the target segment for fast L2 scanning, or accept slower scans. See Multi-VLAN Deployment and Limitations — Layer 2 vs Layer 3.

4. Review your subnet list: Periodically audit your configured subnets and remove any that are no longer needed or contain no relevant hosts.

Topology Empty After Discovery

Symptoms: Discovery completes but topology shows nothing

Check these:

1. Discovery errors: Check Discover > Sessions for failures
2. Network filter: Check topology options panel — wrong network may be selected
3. Refresh mode: Press "Rebuild" or change from manual to auto to get live updates
4. Service filters: Category filters may be hiding everything
5. Reachability: Verify daemon can actually reach the target network

Discovery Fails with "CONCURRENT_SCANS too high"

Symptoms: Daemon crashes or runs out of memory during scans

Solution: Reduce concurrent scans in daemon configuration:

Docker:

environment:
  - SCANOPY_CONCURRENT_SCANS=10 # Reduce from default

Binary:

scanopy-daemon --concurrent-scans 10 ...

See Daemon Configuration for recommended values.

"Too Many Open Files" Error

Symptoms: Critical error scanning: Too many open files (os error 24) in daemon logs

Causes: System file descriptor limit is too low for the configured concurrent scans.

Solutions:

1. Reduce concurrent scans (easiest):

   environment:
     - SCANOPY_CONCURRENT_SCANS=10

2. Increase system file descriptor limit:

   # Check current limit
   ulimit -n
   
   # Increase temporarily
   ulimit -n 65535
   
   # Increase permanently (add to /etc/security/limits.conf)
   * soft nofile 65535
   * hard nofile 65535

3. For Docker: Add to your daemon container:

   ulimits:
     nofile:
       soft: 65535
       hard: 65535

Getting Help

If your issue isn't covered here:

• Discord: Join our Discord community
• GitHub Issues: Open an issue