symfony/http-foundation · error · UnexpectedValueException

Parameter value " " cannot be converted to "bool".

Error message

Parameter value "%s" cannot be converted to "bool".

What it means

ParameterBag::getBoolean() converts a stored parameter to a bool using PHP's FILTER_VALIDATE_BOOL with FILTER_NULL_ON_FAILURE. If the filter cannot interpret the value as a boolean (it returns null), the method throws UnexpectedValueException with the parameter's key in the message. This guards callers from silently getting a wrong default for genuinely invalid stored values.

Solutions

1. Store only canonical boolean strings ('true'/'false', '1'/'0', 'on'/'off', 'yes'/'no') in the parameter bag
2. Read the value and convert manually with a filter_var($bag->get('key'), FILTER_VALIDATE_BOOL) plus your own fallback
3. Catch UnexpectedValueException and apply an application-level default
4. Fix the config source (env var, yaml file) that supplied the bad value

Example fix

// before
$debug = $bag->getBoolean('debug'); // throws if 'debug' => 'enabled'
// after
$debug = filter_var($bag->get('debug'), \FILTER_VALIDATE_BOOL, ['flags' => \FILTER_NULL_ON_FAILURE]) ?? false;

$v = $bag->has($key) ? $bag->get($key) : null;
if (null !== $v && !is_bool($v) && !in_array(strtolower((string) $v), ['1','0','true','false','on','off','yes','no'], true)) {
    throw new \InvalidArgumentException("$key is not a boolean: ".get_debug_type($v));
}

function isBoolLike(mixed $v): bool {
    return is_bool($v) || in_array(strtolower((string) $v), ['1','0','true','false','on','off','yes','no'], true);
}

try {
    $flag = $bag->getBoolean('key');
} catch (\UnexpectedValueException $e) {
    $flag = false; // or log + default
}

When it happens

Trigger: Calling $bag->getBoolean('key') when the stored value is a non-boolean non-coercible string like 'yes-not', 'on/off' misspellings, an array, or an object. Only '1','0','true','false','on','off','yes','no' (case-insensitive) convert.

Common situations: Config values read from env vars or YAML/JSON where 'True', 'enabled', or integers other than 0/1 are stored; a parameter accidentally set to an array.

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.

Related errors

• Parameter " " cannot be converted to enum
• Parameter value " " cannot be filtered.
• Invalid URI: Scheme is malformed.
• The "sameSite" parameter value is not valid.
• The following options are not supported

AI-assisted analysis of symfony/http-foundation@5aea19cd67 (2026-09-13). Data as JSON: /api/errors/df8002ff563dd928. Report an issue: GitHub.

Appendix: source

Thrown at ParameterBag.php:176

    /**
     * Returns the parameter value converted to integer.
     *
     * @throws UnexpectedValueException if the value cannot be converted to integer
     */
    public function getInt(string $key, int $default = 0): int
    {
        return $this->filter($key, $default, \FILTER_VALIDATE_INT, ['flags' => \FILTER_REQUIRE_SCALAR | \FILTER_NULL_ON_FAILURE]) ?? throw new UnexpectedValueException(\sprintf('Parameter value "%s" cannot be converted to "int".', $key));
    }

    /**
     * Returns the parameter value converted to boolean.
     *
     * @throws UnexpectedValueException if the value cannot be converted to a boolean
     */
    public function getBoolean(string $key, bool $default = false): bool
    {
        return $this->filter($key, $default, \FILTER_VALIDATE_BOOL, ['flags' => \FILTER_REQUIRE_SCALAR | \FILTER_NULL_ON_FAILURE]) ?? throw new UnexpectedValueException(\sprintf('Parameter value "%s" cannot be converted to "bool".', $key));
    }

    /**
     * Returns the parameter value converted to an enum.
     *
     * @template T of \BackedEnum
     *
     * @param class-string<T> $class
     * @param ?T              $default
     *
     * @return ?T
     *
     * @psalm-return ($default is null ? T|null : T)
     *
     * @throws UnexpectedValueException if the parameter value cannot be converted to an enum
     */
    public function getEnum(string $key, string $class, ?\BackedEnum $default = null): ?\BackedEnum
    {

View on GitHub (pinned to 5aea19cd67)