maigret/TROUBLESHOOTING.md

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:

1. Raise the timeout. The default is 30 seconds. On mobile networks or for slow sites, bump it:

   maigret user --timeout 60
   

2. Retry failed checks. Transient 5xx / timeouts often clear on a second try:

   maigret user --retries 2
   

3. 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
   

4. 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.

".onion / .i2p sites are skipped"

These sites only load through the matching gateway. Start your Tor or I2P daemon first, then:

# Tor
maigret user --tor-proxy socks5://127.0.0.1:9050

# I2P
maigret user --i2p-proxy http://127.0.0.1:4444

Maigret does not launch or manage these daemons — they must already be running.

"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.