Troubleshooting

If something is not working as expected, the page below covers the most common issues. For installation-specific problems (download, OS-specific permissions, SSL certificate errors at first launch), see Installation, which has its own troubleshooting section.

Launch & License

"Invalid license" or "authentication failed"

In nine cases out of ten this is system clock drift. The license validation uses cryptographic signatures keyed against UTC time. Your clock must be accurate to within one second.

Fix:

• Linux: sudo timedatectl set-ntp on && sudo ntpdate -s time.nist.gov
• macOS: sudo sntp -sS time.apple.com
• Windows: Settings → Time & Language → Date & Time → Sync now

Restart the application.

"Cannot connect to license server"

The toolkit could not reach our licensing endpoint.

Check:

• Internet connection (ping 8.8.8.8 or load any website).
• Firewall is not blocking outbound HTTPS to secure.zerotrace.pw.
• VPN or proxy is not interfering — try without.

If your network blocks outbound connections to non-allowlisted hosts, allowlist secure.zerotrace.pw on port 443.

"SSL certificate verification failed"

The most common cause is outdated application — the bundled CA certificates have aged out.

Fix:

1. Open your ZeroTrace Dashboard.
2. Download the latest version.
3. Uninstall the current version completely.
4. Install the latest version.
5. Launch.

See Installation → SSL/Certificate Errors for full reinstall steps per platform.

"Session expired" mid-investigation

Three-hour sessions are expected. Restart the application; a new session begins.

If sessions are expiring far short of three hours, your system clock may be drifting during the session — fix the clock as above.

Network & Tool Failures

A specific tool returns "rate limited"

Public sources rate-limit per IP. If you have run the same tool many times in a short window, the public source has temporarily throttled you.

Fix:

• Wait. Most public-source rate limits reset within minutes.
• If you have many queries to run, use the tool's bulk paste mode — the toolkit's built-in throttling is gentler than rapid one-at-a-time runs.
• Configure a proxy in settings to spread queries across multiple exit IPs (see Proxy & Anonymity).

A specific tool returns "source unavailable"

The public source the tool relies on is down or unreachable. The result will indicate which source failed.

Fix:

• Check the source's status page if it has one.
• Wait and retry.
• For tools that have multiple sources (DNS lookup, IP reputation, DNS history), the result will surface partial coverage — the working sources still contribute.

"DNS resolution failed"

Your machine could not resolve a hostname. Common causes:

• DNS server unreachable.
• VPN routing DNS to a server that is not responding.
• The hostname truly does not exist (the tool is reporting accurately).

Fix:

• Run nslookup <hostname> from your terminal to confirm.
• Check your DNS resolver in OS settings.
• If on a VPN, run the VPN detection tool — DNS-leak status tells you whether DNS is going through the VPN.

Proxy configured but not used

Make sure the proxy is set in Settings → Proxy with the correct protocol (HTTP / HTTPS / SOCKS4 / SOCKS5) and credentials. The "Test proxy" button confirms reachability.

If the test passes but tools still seem direct, restart the application after changing proxy settings.

Performance

A bulk-paste run is slower than expected

Public-source rate limits dominate bulk performance. A list of 500 inputs against a tool that hits a rate-limited public source may take many minutes.

What you can do:

• Use the cancel button if the run has been going far longer than the per-tool documentation suggests.
• Split very large batches into smaller chunks across separate sessions.
• For tools with multiple sources, the slowest source paces the batch — consider running with only the faster sources enabled (where the tool exposes the choice).

The application uses a lot of memory

Profiles with thousands of findings hold each finding's full result envelope in memory. For very large profiles:

• Filter to the findings you need; the filtered view is what is rendered, not the entire set.
• Split the profile into themed sub-profiles.
• Restart the application periodically (a fresh session reloads only the profile metadata, not every finding).

The UI feels sluggish

Likely a profile with many thousands of findings being rendered at once. Filter, or restart.

If sluggishness happens on a fresh session against a small profile, contact support — that is unusual and worth investigating.

Exports & Reports

PDF export takes a long time

Large profiles with many embedded screenshots or large findings can take some time to render. The export progress bar shows what is happening.

If the export hangs (no progress for several minutes), cancel and try again. If it consistently hangs, a particular finding may have content that breaks the export — try selecting subsets of findings until you isolate which.

PDF text is rendered as blank rectangles

Font rendering issue, usually OS-level. Reinstall or update the system fonts; on Linux, install ttf-mscorefonts-installer or equivalent.

Markdown export contains broken table rows

Markdown table-row escaping for cells with pipes (|) inside them is a known limitation. Use the JSON export when fidelity is critical.

CSV export is missing nested fields

CSV-flattening loses some nested-object fidelity by design. For structured-data fidelity, use JSON.

Tool-specific issues

Image-metadata tool says "no GPS" but I can see GPS in another tool

The other tool may be reading GPS from a sidecar XMP file, geotagging metadata service, or platform-cached location. EXIF GPS comes from the file itself.

If the file is from a social-media download, the platform almost certainly stripped the GPS during upload. Try the original file from the source camera.

Username search reports a profile as "not found" but I know it exists

Possible reasons:

• The platform changed its profile-existence check pattern (we update with each release; report it for the next update).
• The profile is private / restricted in a way that hides it from anonymous probes.
• The handle's case differs (most platforms are case-insensitive, but a few are not).
• The platform is rate-limiting our probes from your IP.

Try with the casing exactly as the user displays it; try without the leading @; try after a few minutes.

TLS inspector returns "handshake failed"

The server may not support modern TLS, may require a specific SNI / cipher, or may rate-limit handshakes from your IP. The error message indicates which step failed.

For self-signed or expired certs, the inspector still returns the cert details — the "handshake failed" only triggers for true failures.

Aerial comparator panels are blank

Imagery providers occasionally rate-limit free tile fetches. Wait a few minutes and reload.

If only one provider's panel is blank but others work, that provider is throttling specifically; the other providers will show the same coordinate just fine.

Data & Profiles

A profile is missing findings I am sure I pinned

Findings only persist after the profile saves. If the application crashed or was force-closed before save, in-flight findings can be lost.

Most profile changes auto-save within a few seconds. If you want to be certain before closing, the file menu's "Save profile" forces an immediate save.

A profile shows the wrong findings

Filters may be applied. Clear filters (top-right of the findings panel) to confirm the profile contents.

"Cannot open profile" or "profile corrupted"

Profile files are local on disk. Check the file's integrity; for older profile-format mismatches, the toolkit attempts an automatic upgrade.

If a profile is genuinely corrupted, contact support — recovery from the file is sometimes possible.

Updates & Versions

A new version is available but the application does not auto-update

The toolkit does not auto-update — that would conflict with the local-control philosophy. Update manually via the dashboard.

After updating, my settings are gone

Settings are stored alongside profiles in your user-config directory. They should persist across updates. If they are gone after an update, the application could not find the settings file — check that the user-config directory has not been moved or its permissions changed.

When to contact support

If the issue is not covered above, contact support through your ZeroTrace Dashboard. Useful information to include:

• Application version (Settings → About).
• Operating system and version.
• The exact error message or behaviour.
• Steps to reproduce.
• Voluntary log attachment (Settings → Logs → Export).