What causes "Cache value for key [%s] must be an integer, %s given." in laravel/framework?

Pass an int default: Cache::integer('key', 0).

laravel/framework · error · InvalidArgumentException

Cache value for key [%s] must be an integer, %s given.

Error message

Cache value for key [%s] must be an integer, %s given.

What it means

Thrown by Cache\Repository::integer() when the stored value is neither an int nor a numeric string that filter_var(FILTER_VALIDATE_INT) accepts. Unlike string(), integer() will coerce numeric strings, so this fires only for genuinely non-integer data (arrays, bools, non-numeric strings, null).

Source

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

     * @param  (\Closure():(int|null))|int|null  $default
     *
     * @throws \InvalidArgumentException
     */
    public function integer($key, $default = null): int
    {
        $key = enum_value($key);

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

        if (is_int($value)) {
            return $value;
        }

        if (filter_var($value, FILTER_VALIDATE_INT) !== false) {
            return (int) $value;
        }

        throw new InvalidArgumentException(
            sprintf('Cache value for key [%s] must be an integer, %s given.', $key, gettype($value))
        );
    }

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

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

View on GitHub (pinned to bd6b5437e6)

Solutions

Pass an int default: Cache::integer('key', 0).
Fix the writer to store a real int: Cache::put('key', (int) $value).
For float-derived counts use Cache::float() or cast before storing.
Clear the bad entry with Cache::forget('key').

Example fix

// before
$count = Cache::integer('page.views');

// after
$count = Cache::integer('page.views', 0);
Cache::put('page.views', (int) $count, $ttl);

Defensive patterns

Strategy: type-guard

Validate before calling

$value = Cache::get('page.views');
if (! is_int($value) && filter_var($value, FILTER_VALIDATE_INT) === false) {
    $value = 0;
}

Type guard

function isCachedInt(string $key): bool {
    $v = Cache::get($key);
    return is_int($v) || filter_var($v, FILTER_VALIDATE_INT) !== false;
}

Try / catch

try {
    $count = Cache::integer('page.views', 0);
} catch (\InvalidArgumentException $e) {
    $count = 0;
    Cache::forget('page.views');
}

Prevention

Pass an int default: Cache::integer('key', 0).
Store counters with (int) and use Cache::increment() for atomic ints.
Avoid caching floats under keys read by integer().

When it happens

Trigger: Calling Cache::integer('key') when the stored value is an array, bool, object, the string 'abc', or null because the key is missing and no int default was passed.

Common situations: Storing a counter via Cache::put('count', ['n' => 1]) and reading it with integer(); a missing key combined with no default; a value cached as a float like '1.5' which FILTER_VALIDATE_INT rejects.

Related errors

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