laravel/framework · error · RuntimeException

The database connection does not support escaping arrays.

Error message

The database connection does not support escaping arrays.

What it means

Thrown by Connection::escape() when the value passed is a PHP array. The generic escape() only handles scalar/null/bool and explicitly rejects arrays because SQL cannot embed a multi-value literal safely. Array values should be turned into an IN (...) via parameter binding or escaped element-by-element.

Source

Thrown at src/Illuminate/Database/Connection.php:1179

     *
     * @param  string|float|int|bool|null  $value
     * @param  bool  $binary
     * @return string
     *
     * @throws \RuntimeException
     */
    public function escape($value, $binary = false)
    {
        if ($value === null) {
            return 'null';
        } elseif ($binary) {
            return $this->escapeBinary($value);
        } elseif (is_int($value) || is_float($value)) {
            return (string) $value;
        } elseif (is_bool($value)) {
            return $this->escapeBool($value);
        } elseif (is_array($value)) {
            throw new RuntimeException('The database connection does not support escaping arrays.');
        } else {
            if (str_contains($value, "\00")) {
                throw new RuntimeException('Strings with null bytes cannot be escaped. Use the binary escape option.');
            }

            if (preg_match('//u', $value) === false) {
                throw new RuntimeException('Strings with invalid UTF-8 byte sequences cannot be escaped.');
            }

            return $this->escapeString($value);
        }
    }

    /**
     * Escape a string value for safe SQL embedding.
     *
     * @param  string  $value
     * @return string

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Use parameter bindings / whereIn() instead of manually escaping arrays.
2. Flatten and escape each element: implode(',', array_map(fn ($v) => $connection->escape($v), $array)).
3. Validate that the input is scalar before calling escape(), and reject or normalize arrays upstream.
4. Switch to a query builder method that accepts arrays natively (whereIn, whereJsonContains).

Example fix

// before
$sql = '... where id in ('.DB::connection()->escape($request->input('ids')).')';

// after
$rows = DB::table('users')->whereIn('id', $request->input('ids', []))->get();

$value = $request->input('ids');
if (is_array($value)) {
    // use whereIn, or escape each element separately
    $rows = DB::table('t')->whereIn('id', $value)->get();
    return;
}
$sql = '... where id = '.$connection->escape($value);

function isEscapeableScalar(mixed $v): bool {
    return $v === null || is_scalar($v) || $v instanceof \Stringable;
}

When it happens

Trigger: Calling $connection->escape($array) directly, or routing user input that is sometimes an array into a raw where clause; using escape() inside a custom builder/macro that receives a variadic list; DB::raw() + escape on request input that is an array (e.g. ?ids[]=1).

Common situations: Building WHERE IN clauses by hand with escape(); passing $_GET array params into a raw expression; a cast or accessor that returns an array reaching escape().

Related errors

• Strings with null bytes cannot be escaped. Use the binary es
• Strings with invalid UTF-8 byte sequences cannot be escaped.
• The given password does not match the current password.
• You requested {$requested} items, but there are only {$count
• $count items were found.

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