What causes "Array value for key [%s] must be a string, %s found." in laravel/framework?

Pass a string default: Arr::string($data, 'name', '').

laravel/framework · error · InvalidArgumentException

Array value for key [%s] must be a string, %s found.

Error message

Array value for key [%s] must be a string, %s found.

What it means

Thrown by Arr::string() when the value resolved via Arr::get() fails is_string(). Non-string scalars, objects with __toString (they are still not is_string), arrays, bools, ints, or null (missing key, no string default) all trigger it.

Source

Thrown at src/Illuminate/Collections/Arr.php:1193

     * @param  int-mask-of<SORT_REGULAR|SORT_NUMERIC|SORT_STRING|SORT_LOCALE_STRING|SORT_NATURAL|SORT_FLAG_CASE>  $options
     * @return array<TKey, TValue>
     */
    public static function sortRecursiveDesc($array, $options = SORT_REGULAR)
    {
        return static::sortRecursive($array, $options, SortDirection::Descending);
    }

    /**
     * Get a string item from an array using "dot" notation.
     *
     * @throws \InvalidArgumentException
     */
    public static function string(ArrayAccess|array $array, string|int|null $key, ?string $default = null): string
    {
        $value = Arr::get($array, $key, $default);

        if (! is_string($value)) {
            throw new InvalidArgumentException(
                sprintf('Array value for key [%s] must be a string, %s found.', $key, gettype($value))
            );
        }

        return $value;
    }

    /**
     * Conditionally compile classes from an array into a CSS class list.
     *
     * @param  array<string, bool>|array<int, string|int>|string  $array
     * @return ($array is array<string, false> ? '' : ($array is '' ? '' : ($array is array{} ? '' : non-empty-string)))
     */
    public static function toCssClasses($array)
    {
        $classList = static::wrap($array);

        $classes = [];

View on GitHub (pinned to bd6b5437e6)

Solutions

Pass a string default: Arr::string($data, 'name', '').
Cast at the source: (string) $value before it lands in the array.
Use Arr::get() + is_string() if the value type legitimately varies.
Fix the dot path so it resolves to a genuine string leaf.

Example fix

// before
$name = Arr::string($payload, 'customer.name');

// after
$name = Arr::string($payload, 'customer.name', '');
// or coerce
$v = Arr::get($payload, 'customer.name');
$name = is_string($v) ? $v : (string) $v;

Defensive patterns

Strategy: type-guard

Validate before calling

$value = Arr::get($payload, 'customer.name');
if (! is_string($value)) {
    $value = is_null($value) ? '' : (string) $value;
}

Type guard

function arrayKeyIsString(array $array, string $key): bool {
    return is_string(Arr::get($array, $key));
}

Try / catch

try {
    $name = Arr::string($payload, 'customer.name', '');
} catch (\InvalidArgumentException $e) {
    $name = (string) Arr::get($payload, 'customer.name', '');
}

Prevention

Pass a string default to Arr::string().
Cast non-string leaves with (string) before reading.
Verify the dot path resolves to a leaf, not an array node.

When it happens

Trigger: Calling Arr::string($data, 'name') when the value is an int ID, an array, an object, or null because the key is missing and $default is null.

Common situations: Decoded JSON where a field is sometimes a string and sometimes null; reading an enum backed value; a dot path that lands on an array element instead of a leaf string.

Related errors

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