laravel/framework · error · RuntimeException

The database connection does not support escaping binary val

Error message

The database connection does not support escaping binary values.

What it means

Thrown by the base Connection::escapeBinary() (which is the default implementation). Every concrete driver (MySQL, Postgres, SQLite, SQL Server) overrides escapeBinary() to produce the driver-specific literal; only a base/abstract Connection that has not been subclassed for a driver would hit the fallback.

Source

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

     * @param  bool  $value
     * @return string
     */
    protected function escapeBool($value)
    {
        return $value ? '1' : '0';
    }

    /**
     * Escape a binary value for safe SQL embedding.
     *
     * @param  string  $value
     * @return string
     *
     * @throws \RuntimeException
     */
    protected function escapeBinary($value)
    {
        throw new RuntimeException('The database connection does not support escaping binary values.');
    }

    /**
     * Determine if the database connection has modified any database records.
     *
     * @return bool
     */
    public function hasModifiedRecords()
    {
        return $this->recordsModified;
    }

    /**
     * Indicate if any records have been modified.
     *
     * @param  bool  $value
     * @return void
     */

View on GitHub (pinned to bd6b5437e6)

Solutions

Use the correct driver-specific Connection class (MySqlConnection, PostgresConnection, etc.) which overrides escapeBinary().
If you wrote a custom Connection subclass, override escapeBinary($value) to produce the driver's binary literal format.
Avoid inline binary escaping entirely; bind the value as a parameter via a prepared statement.
Register a custom driver resolver via Connection::resolver() to map your driver name to a Connection that supports binary.

Example fix

// before
$conn = new \Illuminate\Database\Connection($pdo, $db, $prefix);
$conn->escape($blob, binary: true); // throws

// after
$conn = new \Illuminate\Database\SQLiteConnection($pdo, $db, $prefix);
$conn->escape($blob, binary: true); // uses SQLite's x'' hex literal

Defensive patterns

Strategy: type-guard

Validate before calling

if (! method_exists($connection, 'escapeBinary') || (new \ReflectionMethod($connection, 'escapeBinary'))->getDeclaringClass()->getName() === \Illuminate\Database\Connection::class) {
    // base class fallback: don't inline-escape; bind instead
    DB::table('t')->where('col', $binary)->get();
}

Type guard

function supportsBinaryEscape(\Illuminate\Database\Connection $c): bool {
    return (new \ReflectionMethod($c, 'escapeBinary'))->getDeclaringClass()->getName()
        !== \Illuminate\Database\Connection::class;
}

Prevention

Use driver-specific Connection subclasses (MySQL/Postgres/SQLite/SQL Server).
For custom drivers, override escapeBinary() in your Connection subclass.
Prefer parameter binding for binary values over inline escaping.
Register a Connection::resolver() for any custom driver name.

When it happens

Trigger: Calling $connection->escape($value, binary: true) on a Connection that is the base Illuminate\Database\Connection rather than a driver-specific subclass, or on a custom Connection subclass that forgot to override escapeBinary().

Common situations: A custom driver connection class extending Connection directly without implementing escapeBinary(); using a generic Connection in a polyglot test harness; an unfinished driver adapter package.

Related errors

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