symfony/process · error · InvalidArgumentException

The timeout value must be a valid positive integer or float…

Error message

The timeout value must be a valid positive integer or float number.

What it means

validateTimeout() casts the given value to float and rejects negative numbers (and NaN via comparison semantics) with an InvalidArgumentException. Zero is treated as 'no timeout' (null), but anything negative is invalid.

Solutions

Pass a positive numeric value (int/float) in seconds
Parse duration strings yourself before passing (e.g. convert '30s' to 30.0)
Use 0 or null to disable the timeout instead of a negative number

Example fix

// before
$process->setTimeout('30s');
// after
$process->setTimeout(30.0);

Defensive patterns

Strategy: validation

Validate before calling

$t = (float) $timeout;
if ($t < 0 || is_nan($t)) { throw new InvalidArgumentException('timeout must be >= 0'); }
$process->setTimeout($t);

Try / catch

try { $process->setTimeout($timeout); } catch (InvalidArgumentException $e) { /* sanitize and retry */ }

Prevention

Parse duration strings ('30s') to seconds before passing
Reject negative timeout values in your config layer
Use 0 or null explicitly for 'no timeout'

When it happens

Trigger: setTimeout(-1), setIdleTimeout(-5), passing a non-numeric string like '30s' which casts to 0.0 silently, or passing an array/object that cannot be cast to float.

Common situations: Config values with units ('30s', '5m') passed as strings, negative values from misparsed config, null confusion expecting an exception-free path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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

Related errors

AI-assisted analysis of symfony/process@99b85026db (2026-09-14). Data as JSON: /api/errors/2e050ca481537815. Report an issue: GitHub.

Appendix: source

Thrown at Process.php:1432

        $this->requireProcessIsStarted($caller);

        $this->updateStatus($blocking);
    }

    /**
     * Validates and returns the filtered timeout.
     *
     * @throws InvalidArgumentException if the given timeout is a negative number
     */
    private function validateTimeout(?float $timeout): ?float
    {
        $timeout = (float) $timeout;

        if (0.0 === $timeout) {
            $timeout = null;
        } elseif ($timeout < 0) {
            throw new InvalidArgumentException('The timeout value must be a valid positive integer or float number.');
        }

        return $timeout;
    }

    /**
     * Reads pipes, executes callback.
     *
     * @param bool $blocking Whether to use blocking calls or not
     * @param bool $close    Whether to close file handles or not
     */
    private function readPipes(bool $blocking, bool $close): void
    {
        $result = $this->processPipes->readAndWrite($blocking, $close);

        $callback = $this->callback;
        foreach ($result as $type => $data) {
            if (3 !== $type) {

View on GitHub (pinned to 99b85026db)