getgrav/grav · error · InvalidArgumentException

Uri port must be null or an integer between 0 and 65535

Error message

Uri port must be null or an integer between 0 and 65535

What it means

UriPartsFilter::filterPort() accepts only null or an integer in [0, 65535]; anything else — a numeric string (is_int fails), a bool, a float, or an out-of-range integer — throws InvalidArgumentException. It backs AbstractUri::withPort() (declared `?int`, which coerces numeric strings) and the parts constructor, which casts to int before calling, so range violations are the usual live trigger there.

Source

Thrown at system/src/Grav/Framework/Uri/UriPartsFilter.php:93

        return strtolower($host);
    }

    /**
     * Filter Uri port.
     *
     * This method
     *
     * @param int|null $port
     * @return int|null
     * @throws InvalidArgumentException If the port is invalid.
     */
    public static function filterPort($port = null)
    {
        if (null === $port || (is_int($port) && ($port >= 0 && $port <= 65535))) {
            return $port;
        }

        throw new InvalidArgumentException('Uri port must be null or an integer between 0 and 65535');
    }

    /**
     * Filter Uri path.
     *
     * This method percent-encodes all reserved characters in the provided path string. This method
     * will NOT double-encode characters that are already percent-encoded.
     *
     * @param  string $path The raw uri path.
     * @return string       The RFC 3986 percent-encoded uri path.
     * @throws InvalidArgumentException If the path is invalid.
     * @link   http://www.faqs.org/rfcs/rfc3986.html
     */
    public static function filterPath($path)
    {
        if (!is_string($path)) {
            throw new InvalidArgumentException('Uri path must be a string');
        }

View on GitHub (pinned to 6040efed04)

Solutions

1. Cast to int before validating: `$port = (int) $port`
2. Validate the range and treat invalid as 'no port': `($port >= 1 && $port <= 65535) ? $port : null`
3. Use the typed `$uri->withPort($port)` API so string ports coerce early

Example fix

// before
$port = UriPartsFilter::filterPort($env['SERVER_PORT']); // '8080' string or 65536 -> throws

// after
$port = (int) $env['SERVER_PORT'];
$port = ($port >= 1 && $port <= 65535) ? $port : null;
$uri = $uri->withPort($port);

function normalizePort(mixed $port): ?int
{
    $port = (int) $port;
    return ($port >= 1 && $port <= 65535) ? $port : null;
}

function isValidPort(mixed $port): bool
{
    return $port === null || (is_int($port) && $port >= 0 && $port <= 65535);
}

When it happens

Trigger: Passing '8080' as a string directly to filterPort(); a port parsed as int but out of range (0, 65536, 70000, or a negative value); port math that produced a float (`$port * 1.0`) or a boolean from a bad comparison.

Common situations: Ports read from environment variables or headers as strings and passed unfiltered; concatenation/parsing bugs yielding 0 or >65535; config YAML storing the port as a string.

Related errors

• URL must be a string
• Uri scheme must be a string
• Uri user info must be a string
• Uri host must be a string
• Uri path must be a string

AI-assisted analysis of getgrav/grav@6040efed04 (2026-08-17). Data as JSON: /api/errors/1f09cded8aabbf6c. Report an issue: GitHub.