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 base escape() dispatches by type (null, int/float, bool, string, binary) and explicitly rejects arrays, because array-to-SQL literal conversion is driver-specific. Only drivers that override the array branch (e.g. Postgres with array columns) support it.

Solutions

Use a query builder list method (whereIn/whereJsonContains) instead of escaping the array into SQL.
Flatten the array yourself: implode(',', array_map(fn ($v) => $conn->escape($v), $arr)).
If you need literal array syntax, use a driver/connection that overrides escape() for arrays (Postgres).
Cast the array to a scalar (json_encode) before escaping and store it in a JSON/text column.

Example fix

// before
$sql = "WHERE id IN ({$conn->escape([1, 2, 3])})";

// after
$conn->table('users')->whereIn('id', [1, 2, 3])->get();

Defensive patterns

Strategy: validation

Validate before calling

if (is_array($value)) {
    $literal = implode(',', array_map(fn ($v) => $connection->escape($v), $value));
} else {
    $literal = $connection->escape($value);
}

Type guard

function isEscapableScalar(mixed $value): bool {
    return $value === null
        || is_int($value) || is_float($value)
        || is_bool($value) || is_string($value);
}

Try / catch

try {
    $sql = $connection->escape($value);
} catch (\RuntimeException $e) {
    if (is_array($value)) {
        $sql = implode(',', array_map(fn ($v) => $connection->escape($v), $value));
    } else { throw $e; }
}

Prevention

Never escape an array into SQL; use whereIn()/whereJsonContains() for lists.
Validate that values bound into raw SQL fragments are scalars before escaping.
For Postgres array columns, ensure you are on a PostgresConnection that overrides array escaping.

When it happens

Trigger: Calling $connection->escape($arrayValue) or $connection->quote($arrayValue) where $arrayValue is a non-empty array; using a raw where clause that forces an array through escape; binding an array into a statement that the grammar tries to escape literally.

Common situations: Trying to inline a list into a raw SQL fragment; misusing escape() instead of whereIn(); Postgres array column code run against MySQL/SQLite where array escaping is not supported.

Related errors

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/cfd0a9e8426e2006. Report an issue: GitHub.

Appendix: 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 e0f6eb3518)