Troubleshooting

This guide addresses high-frequency issues encountered during everyday platform operations, along with standard diagnostic procedures.

---

1. Scanning Probe (Client) Issues

1. Probe process running, but Web UI shows "Offline"

• Step 1: Check Client Secret
  • The -secret command-line flag passed to testnet-client must match the server's TESTNET_CLIENT_SECRET environment variable character-for-character. Mismatched secrets cause the server to reject registration attempts.
• Step 2: Test Server Reachability
  • Run curl -k -s -o /dev/null -w "%{http_code}\n" https://<server-ip>:3100 on the probe node. A 200 response confirms network reachability and that the port is not blocked by firewall or security group rules (the default deployment publishes port 3100 only).
• Step 3: NTP Clock Synchronization
  • Align probe and server hosts to a common time source (e.g., ntpdate pool.ntp.org) so log timelines can be cross-referenced and TLS certificate validation stays stable.

2. Probe is online, but workflow tasks remain "Queued"

• Verify Node Tool Whitelist:
  • If an online node's tool whitelist does not include the tool used by the task, the dispatcher will not assign the task to it. Open "Scanning Nodes" → "Configure" to review the whitelist (empty means unrestricted).
• Concurrency Saturation:
  • If active jobs consume all configured execution slots on a node, new jobs wait in queue until slots free up.

3. Docker Error: permission denied while trying to connect to the Docker daemon socket

• Cause: The OS user executing testnet-client lacks permissions to access /var/run/docker.sock.
• Resolution:

  sudo usermod -aG docker $USER
  newgrp docker
  # Or grant read/write access directly
  sudo chmod 666 /var/run/docker.sock

---

2. Workflows & Scan Task Issues

1. Workflow stalls at a specific node

• Check Upstream Output Volume:
  • If an upstream stage (e.g., Subdomain Enumeration) yielded zero discovered targets, downstream stages (e.g., Web Probing) gracefully exit without error.
• Inspect Execution Logs:
  • Open "Run Center", find the task, and click "View Logs" to inspect whether tools failed due to target DNS resolution failure or Out-Of-Memory (OOM) crashes.

2. Execution Error: Command not found / Tool not installed

• Native Shell Mode: Ensure binaries (e.g., subfinder, httpx) are installed and present in the system $PATH.
• Docker Mode Recommendation: Prefer containerized tool definitions (e.g., registry.cn-hangzhou.aliyuncs.com/testnet-tools/subfinder:latest). Probes automatically pull images on first execution.

---

3. Asset Inventory Issues

1. Assets imported, but not appearing in the table

• Check Top Project Selector:
  • TestNet enforces strict project isolation. Assets created or imported are pinned to the currently active project. Confirm that your active project matches the target workspace.
• Inspect Quick Filters:
  • Check whether quick filters or advanced query conditions are active. Clear the active filters to expose all records.

2. Why wasn't a duplicate host created?

• Automated Deduplication: TestNet enforces strict deduplication rules:
  • Root domains deduplicated by normalized lowercase FQDN;
  • IP addresses deduplicated by IPv4/IPv6 canonical notation;
  • Web applications deduplicated by standardized URI (scheme + host + port).
• Re-scanning an existing target refreshes the Last Seen timestamp and updates signatures without polluting data tables.

---

4. AI & MCP Integration Issues

1. Claude Desktop / Cursor Error: SSE connection failed (401 Unauthorized)

• Validate API Key:
  • Verify that the Authorization: Bearer <API_KEY> or query parameter matches the key shown in "AI" → "MCP Access".
• Disable Proxy Buffering:
  • When proxying SSE connections through Nginx, disable proxy buffering:

    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 86400s;

---

5. Licensing Issues

1. "License Expired or Invalid Machine ID"

• Cause: Reinstalling the OS or altering network cards modifies the hardware fingerprint.
• Resolution:
  1. Run ./testnet-license show-machine-id on the server host to obtain the current fingerprint.
  2. Request an updated .lic file from your license issuer.
  3. Upload the new file under "System" → "License Management"; the system validates and activates it immediately.

---

Related Documentation

• FAQ — quick answers to common questions
• Setup & Activation — installation and environment variables
• Node Security — probe sandbox and hardening