Troubleshooting

Troubleshooting

Start with the smallest failing command and one source. Provider availability, authentication, quotas, and response formats can change independently of theHarvester.

Confirm the installation

uv run theHarvester -h
uv run python --version

For a packaged installation:

theHarvester -h
python3 --version

theHarvester requires Python 3.14. Source checkouts managed by uv select it from .python-version.

Configuration file messages

On first use, messages saying that api-keys.yaml or proxies.yaml was created under ~/.theHarvester/ are expected.

If the wrong file is read, check the search order:

1. ~/.theHarvester/
2. /etc/theHarvester/
3. /usr/local/etc/theHarvester/

The first existing file wins.

Missing API key

Check the README source matrix. Configure credentials for that provider or choose a keyless source. -q suppresses missing-key notices; it does not make keyed providers work without credentials.

A provider fails, times out, or returns no results

Rerun one source with a small limit and save its summary:

Network activity: provider-facing lookup plus local report writes.

uv run theHarvester -d example.com -b source-name -l 10 -f diagnostic
jq -c 'select(.type == "summary") | {evidence_status, source_executions}' diagnostic.jsonl

Read the source outcome before treating an empty result as a failure. A completed no-results outcome means the provider conversation finished normally. A partial, failed, or rate-limited outcome names a separate coverage problem.

If the source did not complete normally, check:

• provider status and current API documentation;
• credential validity and subscription access;
• provider rate limits or temporary blocking of shared CI/cloud addresses;
• whether the provider documents the target or query type as supported.

Do not post credentials, private targets, account details, or raw provider responses in a public issue.

DNS resolution

-r accepts no value, a resolver IP, comma-separated resolver IPs, or a resolver file you create with one IP per line:

AUTHORIZED_DOMAIN='replace-with-a-domain-you-control'
uv run theHarvester -d "$AUTHORIZED_DOMAIN" -b crtsh -r resolvers.txt

If theHarvester reports invalid resolvers, remove hostnames, comments, blank values, or host:port entries; the resolver list accepts IP addresses only. Check local firewall and DNS policy before substituting public resolvers.

The input is accepted when the invalid-resolver message is gone. A valid resolver list does not guarantee that a name has DNS records.

Screenshots and Chromium

Install the browser used by Playwright:

uv run playwright install chromium

If Chromium reports missing Linux libraries, install the host dependencies recommended by Playwright. Confirm the target is authorized before retrying; screenshots open discovered web services directly.

REST API

Start with:

uv run harvestview --log-level debug

Then open http://127.0.0.1:5000/docs.

• 401 on /api/v1/*: the X-API-Key header or HarvestView browser session does not match.
• 503 on /api/v1/*: THEHARVESTER_API_KEY was not configured before startup.
• 429: a reverse proxy or remote provider applied its own rate limit. harvestview has no built-in request limiter.
• 503 when creating a run: the execution worker is disabled or unavailable.

After correcting the cause, retry GET /api/v1/sources. A successful authenticated response returns the source catalog.

Docker

docker compose ps
docker compose logs theharvester.svc.local

The container runs HarvestView and the REST API on container port 8000, published only as 127.0.0.1:5000 by the supplied Compose file. If startup reports a missing secret, create .secrets/operator-api-key as shown in the installation guide.

File an actionable issue

Include:

• the smallest sanitized reproduction;
• expected and actual behavior;
• operating system, installation method, Python version, and theHarvester version or commit;
• the exact source and options used;
• only the output needed to diagnose the problem.

Use the repository issue forms. Follow SECURITY.md for suspected vulnerabilities.