This guide covers common issues you may encounter when using ADscan and how to resolve them.

Docker mode (default)

Docker daemon not running

Symptoms:

docker info fails
ADscan cannot pull the runtime image
Logs show Unit docker.service could not be found.

Fix:

sudo systemctl enable --now docker
docker info

If docker.service is missing, Docker Engine is not installed (or not installed as a systemd service). Install Docker Engine first, then retry:

Installation guide

Permission denied to `/var/run/docker.sock`

Symptoms:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Fix (recommended):

sudo usermod -aG docker "$USER"
# Log out/in, or run:
newgrp docker
docker ps

Docker CLI points to Podman socket (blocked by default)

Symptoms:

Logs include podman.sock in Docker daemon diagnostics
ADscan shows a message like ADscan requires Docker Engine by default

Why this happens:

ADscan Docker mode is validated against Docker Engine.
If DOCKER_HOST points to Podman API, launcher now blocks by default to avoid unstable mixed runtime behavior.

Fix (recommended):

# Use Docker Engine endpoint
unset DOCKER_HOST
sudo systemctl enable --now docker
docker info

If ADscan detects this mismatch in an interactive session and confirms Docker Engine is reachable, it can offer a session-only auto-remediation prompt to unset DOCKER_HOST and continue automatically (without modifying shell profile files).

Advanced (opt-in Podman API mode):

export ADSCAN_ALLOW_PODMAN_DOCKER_API=1
systemctl --user start podman.socket

`hashcat -I` shows `No devices found/left` inside the ADscan runtime

Symptoms:

Timeroast / Kerberoast / AS-REP cracking starts but fails immediately
system hashcat -I inside ADscan shows No devices found/left
Your host has an NVIDIA GPU, but the container does not see it

Why this happens:

ADscan auto-enables NVIDIA passthrough only when Docker already advertises the NVIDIA runtime on the host
Intel/AMD /dev/dri passthrough stays opt-in for stability
If the container is started without GPU passthrough, hashcat cannot use CUDA/OpenCL devices from the host

Fix (NVIDIA hosts):

# Host terminal, before launching ADscan
export ADSCAN_DOCKER_GPU=nvidia

# If you want best-effort GPU passthrough across supported runtimes:
# export ADSCAN_DOCKER_GPU=auto

# Verify Docker exposes the NVIDIA runtime
docker info | grep -i nvidia

# Optional sanity check on the host
nvidia-smi

You also need nvidia-container-toolkit installed on the host so Docker can honor --gpus all.

Notes:

If GPU passthrough is active, ADscan lets hashcat auto-select the GPU backend
If no GPU is exposed but CPU OpenCL is available, ADscan falls back to CPU OpenCL automatically
If neither backend is available, ADscan now stops early and prints a runtime guidance message instead of continuing into a misleading hashcat --show

`adscan check` says `john` is missing or incompatible inside a VM

Symptoms:

adscan check reports Missing system packages: john
or it reports that John the Ripper is present but incompatible with the CPU exposed by the host/VM
older runtime images may log Sorry, AVX2 is required for this build

Why this happens:

Docker isolates the runtime filesystem and userspace, but it still uses the CPU features exposed by the Linux host/VM
If your Linux guest does not expose AVX2, an AVX2-only john binary will fail even though the image itself is correct
This is common on Kali VMs when the hypervisor presents a reduced virtual CPU model

Fix:

# Refresh to the latest runtime image from the host
adscan update

Current ADscan runtime images ship John as a generic linux-x86-64 build so it works on supported Linux x86_64 hosts and VMs even when AVX2 is not exposed.

If the problem persists after adscan update, verify what the VM exposes:

grep -m1 -i avx2 /proc/cpuinfo || echo "NO_AVX2_ON_HOST"
sudo docker run --rm --entrypoint /bin/sh adscan/adscan-lite-dev:edge -lc 'grep -m1 -i avx2 /proc/cpuinfo || echo "NO_AVX2_IN_CONTAINER"'

If both checks show no AVX2, the remaining fix is on the virtualization side (CPU model / passthrough), not inside ADscan itself.

Host helper unavailable in Docker mode

Symptoms:

ADscan shows Host helper required and blocks adscan start / adscan ci
You see messages like Failed to initialize host helper or socket not found
The ADscan runtime container cannot start or initialise
GUI host file picker falls back immediately and logs ADSCAN_HOST_HELPER_SOCK=<unset>

Why this matters:

In Docker mode, ADscan needs a privileged host helper for host-side operations.
If the helper is not healthy, ADscan intentionally blocks execution to avoid partial/broken runtime.
Running ADscan from a root shell (sudo su / su -) can break user-context assumptions and cause launcher/runtime inconsistencies.
Running adscan from inside the container shell instead of from the host launcher can also break the runtime contract. In that case the helper socket, local resolver context, and launcher markers are missing by design.

Fix checklist:

# 0) Run ADscan as your normal user (recommended)
adscan start

# 1) Docker daemon must be reachable
docker info || sudo docker info

# 2) Ensure daemon is started
sudo systemctl start docker

# 3) Refresh sudo ticket (if prompted in ADscan)
sudo -v

# 4) Inspect helper log emitted by launcher
tail -n 200 ~/.adscan/logs/host-helper.log

# 5) Retry
adscan start

Avoid:

sudo su
adscan start

Use direct launcher execution as your normal user. ADscan elevates only the required host operations internally.

Also avoid:

docker exec -it <adscan-container> bash
adscan start

That container shell is not the supported entrypoint. ADscan must be launched from the host with the official launcher:

adscan start

If this still fails, run:

adscan check -v

and include ~/.adscan/logs/adscan.log plus ~/.adscan/logs/host-helper.log in your support report.

ADscan says the official launcher is required

Symptoms:

ADscan stops early with a panel explaining that the FULL runtime must be launched from the official host launcher
The message mentions missing runtime requirements such as:
- official launcher marker
- host-helper socket
- local resolver IP

Why this happens:

You entered the container manually and ran adscan from there
or the runtime was started without the launcher-managed environment

Fix:

# Install the official launcher on the host if needed
pipx install adscan

# Alternative
pip install adscan

# Then run ADscan from the host terminal
adscan start

If you previously opened a shell inside the container, exit it first. ADscan now blocks this unsupported path intentionally to prevent partial failures later in the workflow.

ADscan returns to the host after cancelling workspace selection

Symptoms:

You press Ctrl+C or cancel the startup workspace picker
ADscan does not enter the interactive shell
You see a Workspace Required panel instead of landing in a partially initialized CLI session

Why this happens:

ADscan now blocks shell startup unless a workspace is active
This prevents follow-on errors where commands try to save credentials, domain state, or artifacts without a workspace context

How to continue:

Retry the workspace picker
Create a new workspace from the startup recovery prompt
Or exit adscan start cleanly and run it again later

This is intentional. ADscan no longer allows entering the main shell without a workspace because that state causes partial failures later.

`Ctrl+C` cancels `start_auth` or `start_unauth`

Symptoms:

You press Ctrl+C during the interactive start_auth or start_unauth wizard
ADscan shows a Start Setup Cancelled panel instead of dropping you into a half-completed flow
You are offered retry/switch/return actions

Why this happens:

ADscan now treats startup wizards as transactional setup flows
Cancelling the wizard should not leave partially collected credentials, target context, or scan state behind
The command stops before any scan execution starts

How to continue:

Choose Retry this setup to re-run the same wizard from the beginning
Choose Switch to start_auth or Switch to start_unauth if you opened the wrong scan mode
Choose Return to the CLI to abort cleanly and continue working in the current shell

This is intentional. Ctrl+C still cancels the prompt, but ADscan now converts that cancellation into a guided recovery flow instead of leaving the command in an ambiguous state.

ADscan says another runtime is already active

Symptoms:

ADscan stops early with a panel titled Another ADscan Runtime Is Active
The message shows the active command, PID, start time, and ADSCAN_HOME
This usually happens when you launch ADscan from a second terminal while another launcher-driven Docker session is still active

Why this happens:

ADscan Docker mode currently supports one active runtime session per ADSCAN_HOME
The launcher/runtime still shares host-side resources such as:
- the host-helper socket
- ~/.adscan/run, ~/.adscan/state, and ~/.adscan/logs
- workspace persistence paths
Starting a second runtime could break helper-backed workflows or overwrite shared state, so ADscan blocks it intentionally

Fix:

# Go back to the terminal where ADscan is already running
# Exit the active ADscan session cleanly, then retry
adscan start

If the active command is not start, wait for that launcher command to finish and then rerun your command.

If you deliberately need isolated parallel sessions, use a separate ADSCAN_HOME with a separate launcher-managed environment. The default supported path is one active Docker runtime session at a time.

`adscan check` fails inside the Docker runtime

Symptoms:

adscan check shows Python Virtual Env: Not required (ADscan Docker runtime)
the final summary says some checks failed

Fix:

# Run this on the host, not inside the container
adscan update

Why:

adscan start and adscan ci both run the same runtime preflight before the session begins.
In Docker mode, a failed check from inside the runtime is often a launcher/runtime image mismatch rather than something adscan check --fix can repair from inside the container.
Refresh the host launcher and runtime image first, then rerun the original command.

Network / DNS issues pulling images

If you see errors like Could not resolve host: github.com or transient TLS/network failures while pulling:

nslookup github.com
nslookup registry-1.docker.io
docker pull adscan/adscan-lite:latest

If your environment enforces proxies, configure Docker proxy settings and verify DNS on the host.

If ADscan prints a DNS preflight warning like:

DNS preflight could not resolve Docker Hub. Image pull may fail.

then resolver health is already failing before the pull starts. Validate host DNS first:

getent hosts registry-1.docker.io
nslookup registry-1.docker.io

If pull output includes:

lookup registry-1.docker.io ... no such host

this is a host resolver/network issue (not an ADscan image bug). Fix DNS and retry.

If pull output includes:

dial tcp [....]:443: connect: network is unreachable

the host cannot reach Docker Hub over the selected route (commonly broken IPv6 path). Verify outbound connectivity and prefer IPv4 routing if IPv6 is unstable.

If pull output includes TLS / x509 errors like:

tls: failed to verify certificate
x509: certificate is not valid for any names
certificate signed by unknown authority

this is usually a proxy / SSL inspection / custom mirror / CA trust problem on the host path to Docker Hub or its CDN.

Fix:

# Verify host time first
date

# Check whether a proxy is being injected
env | grep -i proxy

# Test Docker Hub TLS directly from the host
curl -vI https://registry-1.docker.io/v2/

If your environment intercepts TLS, trust the organization CA in Docker or bypass TLS inspection for Docker Hub / registry CDN endpoints. Do not disable TLS verification globally.

Docker pull times out / gets killed (rc=-9)

On slow networks (or during the first pull), downloading large images can take longer than the default pull timeout. VPNs / proxies / unstable Wi‑Fi can also throttle or stall Docker pulls.

Symptoms:

ADscan shows Failed to pull the ADscan Docker image
Logs include rc=-9 or similar (process killed)

Fix:

# Increase pull timeout (seconds) and retry
adscan install --pull-timeout 3600

To disable the pull timeout entirely:

adscan install --pull-timeout 0

You can also pull manually to verify connectivity:

docker pull adscan/adscan-lite:latest

If pull output includes:

content descriptor ... not found

this is usually a temporary registry/tag consistency issue. Wait briefly and retry.

Emergency compatibility fallback (disabled by default, may use legacy image naming):

ADSCAN_ALLOW_LEGACY_IMAGE_FALLBACK=1 adscan install

Cannot create workspace (Permission denied)

Symptoms:

PermissionError: [Errno 13] Permission denied: '/opt/adscan/workspaces/<name>'
Creating a new workspace fails only in Docker mode

Cause: Your host workspace directory (~/.adscan/workspaces) is owned by root from a previous legacy install or running older versions with sudo. Docker-mode runs the container as your user (--user <uid>:<gid>), so it cannot write to root-owned mounts.

Fix (recommended):

ls -ld ~/.adscan ~/.adscan/workspaces ~/.adscan/logs
sudo chown -R "$USER:$USER" ~/.adscan/workspaces ~/.adscan/logs
chmod 775 ~/.adscan/workspaces ~/.adscan/logs

Newer versions of ADscan will prompt to repair these permissions automatically when needed.

DNS resolution issues (SRV queries / lab DNS quirks)

ADscan discovers domains via SMB, but it relies on DNS SRV records to identify Domain Controllers and to make Kerberos-based tooling work reliably.

Symptoms:

DNS resolution failed for <domain>
Could not obtain the PDC IP for domain <domain>
dig returns FORMERR while nslookup works

Fix checklist:

domain="example.local"
dc_ip="10.10.10.1"

# Confirm the DC answers SRV queries (nslookup is often more permissive)
nslookup -type=srv _ldap._tcp.dc._msdcs."$domain" "$dc_ip"
nslookup -type=srv _ldap._tcp.pdc._msdcs."$domain" "$dc_ip"

# If you prefer dig, some lab DNS servers choke on EDNS/cookies:
dig +noedns +nocookie +time=2 +tries=1 +short @"$dc_ip" _ldap._tcp.dc._msdcs."$domain" SRV
dig +noedns +nocookie +time=2 +tries=1 +short @"$dc_ip" _ldap._tcp.pdc._msdcs."$domain" SRV

# If UDP is blocked/unreliable, force TCP:
dig +tcp +noedns +nocookie +time=2 +tries=1 +short @"$dc_ip" _ldap._tcp.dc._msdcs."$domain" SRV

If these commands work but ADscan still fails, capture:

adscan check -v
tail -n 200 ~/.adscan/logs/adscan.log

Installation Issues

Docker Not Running

Error:

✗ Docker daemon not running
✗ Cannot pull the ADscan runtime image

Solution:

# Check Docker status
sudo systemctl status docker

# Start Docker
sudo systemctl start docker

# Enable Docker on boot
sudo systemctl enable docker

# Verify Docker is running
docker ps

Permission Denied

Error:

✗ Permission denied: ~/.adscan/...

Solution:

# If you previously ran an older version as root, your state dirs may be owned by root.
# Docker-mode runs the container as your user, so these mounts must be writable.
sudo chown -R "$USER:$USER" ~/.adscan/workspaces ~/.adscan/logs
chmod -R u+rwX ~/.adscan/workspaces ~/.adscan/logs

# Verify:
touch ~/.adscan/workspaces/.write_test && rm ~/.adscan/workspaces/.write_test

Scanning Issues

Network Interface Not Found

Error:

✗ Interface 'tun0' not found

Solution:

# List available interfaces
ip addr show

# Check VPN connection
ping 10.10.10.1

# Restart VPN if needed
sudo openvpn --config lab.ovpn

Domain Not Found

Error:

✗ No Active Directory domain found in range

Solutions:

Verify network connectivity:

# Ping domain controller
ping 10.10.10.1

# Check DNS resolution
nslookup dc01.example.local

# Test SMB connectivity
smbclient -L //10.10.10.1 -N

If you see messages like "NETBIOS connection timeout" or repeated SMB timeouts, this is usually a connectivity / VPN / firewall / latency issue (not "no shares found"). Try:

Test a single host instead of a large range

Retry with fewer threads and a larger timeout (example: -t 1 --timeout 30)

Verify TCP/445 is reachable (nc -zv <ip> 445)

Reconnect the VPN and retry

Verify DNS SRV queries (UDP vs TCP):

ADscan discovers domains via SMB, but it relies on DNS SRV records to confirm Domain Controllers and configure DNS locally. In some lab/VPN environments, UDP/53 may be blocked or unreliable while TCP/53 still works.

# Query the DC's DNS directly (SRV record for the PDC)
nslookup -type=srv _ldap._tcp.pdc._msdcs.example.local 10.10.10.1

# If dig returns FORMERR, try disabling EDNS/cookies (common in lab DNS):
dig +noedns +nocookie +time=2 +tries=1 @10.10.10.1 _ldap._tcp.pdc._msdcs.example.local SRV

# If you see "no servers could be reached", try forcing DNS over TCP:
dig +tcp +time=2 +tries=1 @10.10.10.1 _ldap._tcp.pdc._msdcs.example.local SRV

# Also test resolving the DC hostname via the same DNS server:
dig +tcp +short @10.10.10.1 dc01.example.local A

Check firewall rules:

# Required ports:
# - 88 (Kerberos)
# - 389/636 (LDAP/LDAPS)
# - 445 (SMB)
# - 3389 (RDP)

# Test port connectivity
nc -zv 10.10.10.1 445
nc -zv 10.10.10.1 389
nc -zv 10.10.10.1 88

Expand IP range:

# Try broader range if scanning specific subnet
(ADscan:workspace) > set hosts 10.10.10.0/24

Authentication Failed

Error:

✗ Authentication failed for user 'jdoe'

Troubleshooting steps:

Verify credentials:

# Test with NetExec
nxc smb 10.10.10.1 -u 'jdoe' -p 'password'

# Test with smbclient
smbclient //10.10.10.1/IPC$ -U 'DOMAIN\jdoe%password'

Check account status:
- Account may be locked
- Password may have expired
- Account may be disabled
- Wrong domain name
Use NTLM hash instead:

# If password doesn't work, try hash
(ADscan:workspace) > start_auth domain.local 10.10.10.1 jdoe aad3b435b51404eeaad3b435b51404ee:hash

Attack-path graph analysis

ADscan 9.x ships a native graph collector — there is no ADscan-managed BloodHound container any more. Attack paths can be inspected three ways:

From the ADscan CLI using attack_paths <domain> owned (and variants like --tier0-only, --lowpriv).
From the BloodHound-compatible export at ~/.adscan/workspaces/<ws>/domains/<domain>/attack_graph.json. Load that JSON into your own BloodHound CE instance for the graph UI.
From the workspace-level summary panel rendered automatically after authenticated scans.

If a graph node is missing or a path you expect is not surfaced, see adscan-attack-paths-debug for the workspace-level repro tooling.

Critical low-memory preflight blocks Docker-mode commands

Symptoms:

ADscan stops before the runtime container starts with a critical low-memory message
Non-interactive runs (for example CI) fail fast when available RAM is very low

Why this happens:

ADscan applies a global runtime RAM guard in install, start, check, and ci.
Guard thresholds:
- < 1.0 GB available RAM: critical (block or require explicit confirmation)
- 1.0 - 1.5 GB: warning only
- >= 1.5 GB: no low-memory warning

Fix (recommended):

# 1) Free RAM / stop heavy apps
free -h

# 2) Optionally add swap
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 3) Retry command
adscan start

Override (advanced / constrained environments):

adscan install --allow-low-memory
adscan start --allow-low-memory
adscan check --allow-low-memory
adscan ci --allow-low-memory -- <ci-args>

Loading the BloodHound-compatible export into your own BH CE instance

ADscan does not bundle BloodHound CE any more. After each authenticated scan, the native graph collector writes a BloodHound-compatible JSON to:

~/.adscan/workspaces/<ws>/domains/<domain>/attack_graph.json

If you want to explore the graph visually in BloodHound CE, run your own instance and upload that file via the BloodHound UI Upload Data action. ADscan's container does not need to talk to your BloodHound instance — the JSON export is the only handoff.

Credential Issues

Hash Cracking Failed

Error:

✗ Failed to crack hash after 1000000 attempts

Solutions:

Use custom wordlist:

# Copy custom wordlist to ADscan
cp custom_passwords.txt ~/.adscan/wordlists/

# ADscan will prompt to select wordlist

Use external cracking:

# Export hash
cat ~/.adscan/workspaces/<workspace>/asrep/hashes.txt

# Crack with hashcat
hashcat -m 18200 hashes.txt rockyou.txt

# Crack with john
john --wordlist=rockyou.txt hashes.txt

No Credentials Found

Scenario: Scan completes but no credentials discovered.

Troubleshooting:

Check scan mode:

# Ensure authenticated scan was run
(ADscan:workspace) > start_auth domain.local 10.10.10.1 user pass

Review BloodHound paths:
- Open BloodHound UI
- Search for your user
- Look for "Shortest Path to Domain Admins"
- Check for exploitable paths
Try different attack vectors:
- AS-REP roasting (unauthenticated)
- Kerberoasting (authenticated)
- Password spraying
- SMB relay
- LLMNR/NBT-NS poisoning

Workspace Issues

Workspace Corruption

Error:

✗ Failed to load workspace data

Solution:

# Check workspace integrity
ls -la ~/.adscan/workspaces/<workspace>/

# Recreate workspace if corrupted
(ADscan) > workspace delete corrupted_workspace
(ADscan) > workspace create new_workspace

Disk Space Full

Error:

✗ No space left on device

Solution:

# Check disk usage
df -h ~/.adscan/

# Clear old workspaces
(ADscan) > workspace list
(ADscan) > workspace delete old_workspace

# Or manually delete
rm -rf ~/.adscan/workspaces/old_workspace/

# Clear logs
rm ~/.adscan/logs/*.log

Performance Issues

Slow Scanning

Symptoms:

Enumeration takes very long
Timeouts during scanning

Solutions:

Reduce target range:

# Scan specific DC instead of entire subnet
(ADscan:workspace) > set hosts 10.10.10.1

Check network latency:

# High latency affects performance
ping -c 10 10.10.10.1

Use verbose mode for debugging:

adscan start -v

High Memory Usage

Solution:

# Monitor memory usage
htop

# Restart ADscan if memory leak suspected
# (exit and restart the CLI)

Error Messages

"Command not found"

Error:

bash: adscan: command not found

Solution:

# Check installation
which adscan

# If installed with pipx
pipx ensurepath
source ~/.bashrc

# If installed with pip
pip show adscan

# Reinstall if needed
pipx install --force adscan

"Module not found"

Error:

ModuleNotFoundError: No module named 'rich'

Solution:

# Reinstall dependencies
adscan install

# Or manually install
pip install -r requirements.txt

Networking Issues

Git clone / pip VCS installs fail: `Could not resolve host: github.com`

Some tools are installed from pinned Git commits. If your system cannot resolve GitHub (DNS outage, captive network, restricted environment), installs will fail.

Symptoms:

fatal: unable to access 'https://github.com/...': Could not resolve host: github.com

Checks:

nslookup github.com
curl -I https://github.com

Fix:

Ensure your DNS works (see the DNS section above).
If you are in a restricted network, you may need to allow outbound HTTPS/DNS or use a different network/VPN.

Getting Help

If you're still experiencing issues:

Check logs:

tail -f ~/.adscan/logs/adscan.log

Enable debug mode:

adscan start --debug

Report issue on GitHub:
- GitHub Issues
- Include logs, error messages, and steps to reproduce
Join Discord:
- ADscan Discord
- Get real-time help from the community

🛠️ Troubleshooting

On this page