laravel/framework · error · RuntimeException

The database connection does not support escaping binary…

Error message

The database connection does not support escaping binary values.

What it means

Thrown by the base Connection::escapeBinary(), which is a deliberate stub. The framework expects each concrete driver to override escapeBinary() to emit the correct binary-literal syntax for its RDBMS (MySQL x'..' hex, Postgres bytea '\x..' , SQL Server 0x..). Calling escape($value, true) on a connection whose driver did not override it hits the stub.

Solutions

Use the concrete driver connection (MySqlConnection/PostgresConnection/SqlServerConnection), which override escapeBinary().
If you wrote a custom Connection subclass, implement escapeBinary($value) to return the correct literal for your driver.
Prefer parameter binding over literal escaping for binary values: ->where('col', '=', $binary).
Store binary via a model cast / BLOB binding so the driver handles encoding.

Example fix

// before
$conn = new class($pdo, $db, '') extends \Illuminate\Database\Connection {};
$conn->escape($bytes, true);

// after
$conn = new \Illuminate\Database\MySqlConnection($pdo, $db, '');
$conn->escape($bytes, true);

Defensive patterns

Strategy: type-guard

Validate before calling

$conn = DB::connection();
if ($conn instanceof \Illuminate\Database\MySqlConnection
 || $conn instanceof \Illuminate\Database\PostgresConnection
 || $conn instanceof \Illuminate\Database\SqlServerConnection) {
    $sql = $conn->escape($bytes, true);
} else {
    throw new \LogicException('Current connection does not override escapeBinary().');
}

Type guard

function supportsBinaryEscape(\Illuminate\Database\Connection $c): bool {
    return $c instanceof \Illuminate\Database\MySqlConnection
        || $c instanceof \Illuminate\Database\PostgresConnection
        || $c instanceof \Illuminate\Database\SqlServerConnection
        || $c instanceof \Illuminate\Database\MariaDbConnection;
}

Try / catch

try {
    $sql = $connection->escape($bytes, true);
} catch (\RuntimeException $e) {
    // fall back to parameter binding which all drivers handle
    $connection->insert('insert into blobs (data) values (?)', [$bytes]);
}

Prevention

Use parameter binding for binary values instead of literal escaping.
Confirm your custom Connection subclass overrides escapeBinary() if you need literal binary SQL.
Default to concrete driver connections (MySql/Postgres/SqlServer) for binary support.

When it happens

Trigger: Calling $connection->escape($binary, true) on a base Connection or a custom Connection subclass that does not override escapeBinary(); using a fake SQLite connection in tests that subclasses Connection without overriding escapeBinary.

Common situations: Custom Connection subclasses that omit the escapeBinary override; tests using a minimal Connection double; calling escape with binary flag on an unsupported/aggregated connection.

Related errors

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

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