# How the Timeout Parameter Controls Module Execution in Holehe

> Discover how the timeout parameter in Holehe controls module execution. Learn how to set the global timeout to manage HTTP response waiting times and identify rate limits.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: internals
- Published: 2026-08-25

---

**The `-T/--timeout` flag configures a global timeout value (default 10 seconds) for the shared `httpx.AsyncClient`, determining how long each module waits for HTTP responses before treating the request as a failure and marking the result with `rateLimit: True`.**

Holehe is an open-source OSINT tool that checks email addresses against multiple services asynchronously. The **timeout parameter** directly governs the maximum duration each module spends awaiting network responses, creating a trade-off between scan speed and result accuracy.

## CLI Argument Parsing in core.py

The timeout value originates in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), where the argument parser defines the `-T` and `--timeout` flags with a default of 10 seconds:

```python
parser.add_argument("-T","--timeout", type=int , default=10, ...)

```

After parsing, the value is stored in `args.timeout` and used to instantiate the HTTP client between lines 108-114. This single configuration point ensures the timeout is applied consistently across the entire application.

## Propagation to Modules via AsyncClient

Holehe creates one `httpx.AsyncClient` instance using the user-provided timeout, which is then injected into every module:

```python
timeout = args.timeout
client = httpx.AsyncClient(timeout=timeout)

```

All module functions receive this `client` object as a required parameter (e.g., `myspace(email, client, out)`). Because modules share this single client instance, the timeout setting propagates to every HTTP request made during execution, ensuring uniform network behavior without manual configuration per service.

## Execution Impact and Error Handling

When a request exceeds the configured duration, httpx raises a `TimeoutException`. Holehe catches generic exceptions within module logic and interprets them as rate-limit or timeout conditions, setting `"rateLimit": True` in the output dictionary.

For example, in [`holehe/modules/social_media/myspace.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/myspace.py), an initial GET request uses a hard-coded 2-second timeout, but subsequent requests respect the client-wide timeout passed from [`core.py`](https://github.com/megadose/holehe/blob/main/core.py). If the global timeout is reached, the module treats it as a rate limit and stops processing.

### Short vs. Long Timeout Values

- **Shorter timeouts** (e.g., 3 seconds): Accelerate overall scan completion but increase the risk of false negatives, as slower services may be marked as rate-limited before responding.
- **Longer timeouts** (e.g., 30 seconds): Improve accuracy for slow or congested services but significantly extend total execution time, especially if multiple services are unresponsive.
- **Default (10 seconds)**: The original author's balanced setting suitable for most network conditions.

## Practical Configuration Examples

Run Holehe with custom timeout values via the CLI:

```bash

# Default 10-second timeout

holehe example@example.com

# Fast scan with 3-second timeout

holehe example@example.com -T 3

# Tolerant scan for slow networks (20 seconds)

holehe example@example.com --timeout 20

```

For programmatic usage, create the client with a custom timeout before invoking modules directly:

```python
import httpx
from holehe.core import import_submodules, get_functions

modules = import_submodules("holehe.modules")
websites = get_functions(modules)

# Configure 5-second timeout

client = httpx.AsyncClient(timeout=5)

# Execute specific module

import holehe.modules.social_media.myspace as myspace_mod
await myspace_mod.myspace("example@example.com", client, [])

```

## Summary

- The **timeout parameter** is defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) with a default value of 10 seconds.
- A single `httpx.AsyncClient` instance shares the timeout setting across all modules.
- Exceeded timeouts result in `TimeoutException`, which modules catch and report as `rateLimit: True`.
- Adjusting the value trades off between scan speed (short timeouts) and reliability (long timeouts).

## Frequently Asked Questions

### What is the default timeout value in Holehe?

The default timeout is **10 seconds**, defined in the argument parser within [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). This value is used when the `-T` or `--timeout` flag is not specified.

### How does Holehe handle requests that exceed the timeout limit?

When a request exceeds the configured timeout, httpx raises a `TimeoutException`. Holehe catches this exception in module code and marks the result with `"rateLimit": True`, indicating the check could not complete due to time constraints or rate limiting.

### Can individual modules override the global timeout setting?

While modules generally use the shared client, some may implement specific timeouts for individual requests. For instance, [`myspace.py`](https://github.com/megadose/holehe/blob/main/myspace.py) uses a hard-coded 2-second timeout for an initial GET request, but subsequent requests respect the global client timeout passed from the CLI.

### Does increasing the timeout guarantee finding more accounts?

Not necessarily. A longer timeout only allows more time for slow servers to respond; it does not bypass rate limiting or authentication requirements. However, it can reduce false negatives caused by temporary network latency.