Troubleshooting

Common issues when running Maigret and how to fix them. If none of this helps, open an issue with the output of maigret --version and the exact command you ran.

"Lots of sites fail / timeout / return 403"

This is by far the most common report. It almost always comes from anti-bot protection (Cloudflare, DDoS-Guard, Akamai, etc.) or a slow network — not from a bug in Maigret.

Results vary a lot depending on where you run from. The same command on the same username can produce very different output on:

Mobile internet (4G/5G) — usually the best results. Carrier NAT shares your IP with thousands of real users, so WAFs rarely block it.
Home broadband — generally good, though some ISPs are reputation-flagged.
Hosting / cloud / VPS infrastructure (AWS, GCP, DigitalOcean, Hetzner, etc.) — the worst case. Datacenter IP ranges are blanket-blocked or challenged by most WAFs, so you will see many false negatives and 403s.

If a run looks suspiciously empty, try a different network before assuming Maigret is broken: tether from your phone, switch between Wi-Fi and mobile, or move the run off a VPS onto a residential machine. Comparing results across two networks is also the fastest way to tell whether a missing account is genuinely missing or just blocked on the current IP.

Once you have a sense of the baseline, try these tweaks in order:

Raise the timeout. The default is 30 seconds. On mobile networks or for slow sites, bump it:
```
maigret user --timeout 60
```
Retry failed checks. Transient 5xx / timeouts often clear on a second try:
```
maigret user --retries 2
```
Lower parallelism. Some WAFs rate-limit aggressively. Maigret defaults to 100 concurrent connections (-n / --max-connections) — dropping this makes you look less like a scanner:
```
maigret user -n 20
```
Route through a residential proxy. Datacenter IPs (AWS, GCP, DigitalOcean) are blanket-blocked by many WAFs. A residential / mobile proxy usually fixes this:
```
maigret user --proxy http://user:pass@residential-proxy:port
```
Note: Tor (--tor-proxy) rarely helps here — most WAFs block Tor exit nodes just as aggressively as datacenter IPs. Use Tor only when you actually need to reach .onion sites (see below).

If specific sites always fail regardless of the above, they are likely broken in the database (stale markers, new WAF, site redesign). Report them with --print-errors output so a maintainer can look at the check config.

"No results at all" / "maigret: command not found"

command not found — pip install maigret put the binary under ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows). Add that directory to PATH, or run python3 -m maigret user instead.
Empty output — check that you actually passed a username; maigret alone prints help. Also confirm Python 3.10+ with python3 --version.

"SSL / certificate errors"

Usually caused by a corporate MITM proxy or an outdated certifi bundle.

pip install --upgrade certifi

If you are behind a corporate proxy, set HTTPS_PROXY / HTTP_PROXY environment variables and pass --proxy "$HTTPS_PROXY" so Maigret uses the same route.

Running over Tor, I2P, or Tails OS

Two different goals, two different flags:

Route only .onion / .i2p sites through their gateway (clearweb checks still use your direct connection). Use --tor-proxy / --i2p-proxy:
```
maigret user --tor-proxy socks5://127.0.0.1:9050   # only .onion goes via Tor
maigret user --i2p-proxy http://127.0.0.1:4444     # only .i2p goes via I2P
```
Without these flags, .onion / .i2p sites are silently skipped.
Route the whole run through Tor / a proxy (e.g. on Tails OS, or to anonymise the scan). Use --proxy:
```
# system tor daemon (apt install tor, Tails)
maigret user --proxy socks5://127.0.0.1:9050 --timeout 60 --retries 2

# Tor Browser bundle (different SOCKS port!)
maigret user --proxy socks5://127.0.0.1:9150 --timeout 60 --retries 2
```
Most public WAFs block Tor exits, so expect more UNKNOWNs over Tor than on a residential line — this is the cost of anonymity, not a bug. Raising --timeout to 60 and adding --retries 2 materially reduces noise.

On Tails, torsocks maigret … / torify maigret … do not work — Maigret's HTTP client bypasses libc, so the wrapper has no effect. Use --proxy instead. To install Maigret over Tor: torsocks pip install --user maigret.

Maigret does not launch or manage Tor / I2P daemons — they must already be running.

For the full walkthrough (Tor Browser vs system tor ports, Tails persistence, reports paths), see the Tor, I2P, and proxies page on readthedocs.

"The PDF / XMind / HTML report looks wrong"

PDF — requires weasyprint and its system dependencies (Pango, Cairo, GDK-PixBuf). On Debian/Ubuntu: apt install libpango-1.0-0 libpangoft2-1.0-0. macOS: brew install pango.
XMind — the --xmind flag generates XMind 8 files. XMind 2022+ (Zen / XMind 2023) uses a different format and will not open them. Use XMind 8 or convert via --html.
HTML looks unstyled — open it through a local file path (file:///...), not via a preview pane that strips CSS.

"The site database is out of date"

Maigret auto-fetches a fresh data.json from GitHub once every 24 hours. To force-refresh now:

maigret user --force-update

To run entirely against the local built-in copy (e.g. offline):

maigret user --no-autoupdate

Still stuck?

Open an issue — include your OS, Python version, Maigret version, and the full command.
Ask in GitHub Discussions or the Telegram channel.

5.9 KiB Raw Blame History