laravel/framework · error · RuntimeException

Strings with null bytes cannot be escaped. Use the binary es

Error message

Strings with null bytes cannot be escaped. Use the binary escape option.

What it means

Thrown by Connection::escape() when a string value contains a null byte ("\00"). Null bytes can truncate or terminate SQL on some drivers, so the framework refuses to embed them as text. Such payloads are almost always binary and must be escaped via the binary escape path.

Source

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

     * @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
     */
    protected function escapeString($value)
    {

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Pass the binary flag: $connection->escape($value, binary: true) so escapeBinary() is used.
2. Store the value via a prepared statement with ? binding rather than escaping into the SQL string.
3. Use the AsBinary cast / BinaryCodec for binary UUID/ULID columns on Eloquent models.
4. Detect and reject NUL bytes early if the field is supposed to be text (str_contains($v, "\0")).

Example fix

// before
$sql = '... where signature = '.$conn->escape($blob);

// after
$sql = '... where signature = '.$conn->escape($blob, binary: true);
// or preferred:
DB::table('t')->where('signature', $blob)->get();

if (is_string($value) && str_contains($value, "\0")) {
    // it's binary: use binary escape or bind
    $literal = $connection->escape($value, binary: true);
} else {
    $literal = $connection->escape($value);
}

function looksBinary(string $v): bool {
    return str_contains($v, "\0");
}

When it happens

Trigger: Calling $connection->escape($string) where $string contains embedded NUL bytes; reading encrypted/blob column data into a string then escaping it; concatenating binary UUID (16 raw bytes) into a query.

Common situations: Storing binary UUIDs, encrypted blobs, serialized binary payloads, image headers, or data read from a binary file with file_get_contents().

Related errors

• The database connection does not support escaping arrays.
• The database connection does not support escaping binary val
• Strings with invalid UTF-8 byte sequences cannot be escaped.
• The binary codec format is required.
• Unsupported binary codec format [%s]. Allowed formats are: %

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