What causes "Invalid timeout value: {value}. Timeout must be a positive number." in sherlock-project/sherlock?

Pass a positive number of seconds: `sherlock --timeout 10 username` (sherlock's own default when omitted is positive).

sherlock-project/sherlock · error · ArgumentTypeError

Invalid timeout value: {value}. Timeout must be a positive n

Error message

Invalid timeout value: {value}. Timeout must be a positive number.

What it means

timeout_check() is the validator for the --timeout CLI option (and any programmatic timeout value passed through argparse). It converts the input with float(value) and rejects anything that is not strictly greater than zero by raising argparse's ArgumentTypeError. In CLI context argparse turns this into a usage message and exit code 2; called as a function it propagates as an exception.

Source

Thrown at sherlock_project/sherlock.py:526

def timeout_check(value):
    """Check Timeout Argument.

    Checks timeout for validity.

    Keyword Arguments:
    value                  -- Time in seconds to wait before timing out request.

    Return Value:
    Floating point number representing the time (in seconds) that should be
    used for the timeout.

    NOTE:  Will raise an exception if the timeout in invalid.
    """

    float_value = float(value)

    if float_value <= 0:
        raise ArgumentTypeError(
            f"Invalid timeout value: {value}. Timeout must be a positive number."
        )

    return float_value


def handler(signal_received, frame):
    """Exit gracefully without throwing errors

    Source: https://www.devdungeon.com/content/python-catch-sigint-ctrl-c
    """
    sys.exit(0)


def main():
    parser = ArgumentParser(
        formatter_class=RawDescriptionHelpFormatter,
        description=f"{__longname__} (Version {__version__})",

View on GitHub (pinned to 9100f9d40a)

Solutions

Pass a positive number of seconds: `sherlock --timeout 10 username` (sherlock's own default when omitted is positive).
If the intent was 'wait indefinitely', drop the --timeout flag instead of setting 0 — requests requires a positive numeric timeout.
If a wrapper script computes the value, guard it: use `max(value, some_positive_default)` or substitute a default when the computed value is <= 0.
When calling timeout_check() directly in code, catch argparse.ArgumentTypeError and re-prompt or fall back to a sane default.

Example fix

# before
sherlock --timeout 0 john_doe

# after
sherlock --timeout 10 john_doe

Defensive patterns

Strategy: validation

Validate before calling

from sherlock_project.sherlock import timeout_check

CLITimeout = float  # positive seconds

def safe_timeout(raw) -> float:
    try:
        return timeout_check(raw)
    except ValueError:  # non-numeric
        return 10.0  # sherlock-style default
    except Exception:  # ArgumentTypeError for <= 0
        return 10.0

Type guard

def is_positive_timeout(value) -> bool:
    if isinstance(value, bool):
        return False
    if isinstance(value, (int, float)):
        return value > 0
    try:
        return float(value) > 0
    except (TypeError, ValueError):
        return False

Prevention

Never pass 0 or negative timeouts; there is no 'infinite' value — omit the option to use the default.
In wrapper scripts, clamp computed timeouts: timeout = max(computed, 1).
Remember argparse handles this for CLI use (usage error, exit 2); manual handling is only needed when importing timeout_check().
Distinguish the two failures: non-numeric input raises ValueError from float(); numeric-but-nonpositive raises ArgumentTypeError.

When it happens

Trigger: Running `sherlock --timeout 0 target` or `sherlock --timeout -5 target`; passing a timeout of 0 programmatically via the CLI parser. Note the two neighboring failure modes: a non-numeric string like "--timeout abc" raises ValueError from float(value) at line 523 (not this error), and this error fires only when the value parses to a number <= 0.

Common situations: Scripts that compute timeout from another variable which can legitimately be 0 (e.g. an unset env var defaulting to 0); users assuming 0 means 'no timeout / wait forever'; negative values from misparsed arguments or misconfigured config files feeding the CLI.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of sherlock-project/sherlock@9100f9d40a (2026-08-14). Data as JSON: /api/errors/2bc8636167154cba. Report an issue: GitHub.