laravel/framework · error · InvalidArgumentException

Cache value for key [%s] must be a boolean, %s given.

Error message

Cache value for key [%s] must be a boolean, %s given.

What it means

Thrown by Cache\Repository::boolean() when the stored value fails is_bool(). This accessor does no coercion, so the integers 0/1, the strings 'true'/'false', or null all fail. It exists to guarantee a real bool is returned.

Source

Thrown at src/Illuminate/Cache/Repository.php:327

        );
    }

    /**
     * Retrieve a boolean item from the cache.
     *
     * @param  \UnitEnum|string  $key
     * @param  (\Closure():(bool|null))|bool|null  $default
     *
     * @throws \InvalidArgumentException
     */
    public function boolean($key, $default = null): bool
    {
        $key = enum_value($key);

        $value = $this->get($key, $default);

        if (! is_bool($value)) {
            throw new InvalidArgumentException(
                sprintf('Cache value for key [%s] must be a boolean, %s given.', $key, gettype($value))
            );
        }

        return $value;
    }

    /**
     * Retrieve an array item from the cache.
     *
     * @param  \UnitEnum|string  $key
     * @param  (\Closure():(array<array-key, mixed>|null))|array<array-key, mixed>|null  $default
     * @return array<array-key, mixed>
     *
     * @throws \InvalidArgumentException
     */
    public function array($key, $default = null): array
    {

View on GitHub (pinned to bd6b5437e6)

Solutions

  1. Pass a bool default: Cache::boolean('feature.enabled', false).
  2. Cast at write time: Cache::put('feature.enabled', (bool) $flag, $ttl).
  3. If the source only gives 0/1 or 'true'/'false', normalize before caching (filter_var($v, FILTER_VALIDATE_BOOL)).
  4. Cache::forget('feature.enabled') after fixing the writer.

Example fix

// before
$on = Cache::boolean('feature.flag');

// after
$on = Cache::boolean('feature.flag', false);
Cache::put('feature.flag', (bool) filter_var($env, FILTER_VALIDATE_BOOLEAN), $ttl);
Defensive patterns

Strategy: type-guard

Validate before calling

$value = Cache::get('feature.enabled');
if (! is_bool($value)) {
    // normalize common truthy/falsy representations
    $value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
}

Type guard

function isCachedBool(string $key): bool {
    return is_bool(Cache::get($key));
}

Try / catch

try {
    $on = Cache::boolean('feature.enabled', false);
} catch (\InvalidArgumentException $e) {
    $on = false;
}

Prevention

When it happens

Trigger: Calling Cache::boolean('feature.enabled') when the stored value is 1, 0, '1', 'true', an array, or null (missing key with no bool default).

Common situations: Caching a config flag from an env var that yields 'true'/1 instead of a real bool; storing enabled state as an int from a database column; missing key without a default.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/d600cfdce72165e8.json. Report an issue: GitHub.