laravel/framework · error · RuntimeException

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

Error message

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

What it means

Thrown by Connection::escape() in the string branch when str_contains($value, "\00") is true. A NUL byte inside a string literal would break SQL parsing and is a classic injection/encoding hazard, so the framework refuses to escape it as a string. Binary data must go through the dedicated escapeBinary() path by passing the $binary flag.

Solutions

Pass the binary flag: $connection->escape($value, true) so escapeBinary() is used.
Use a parameterized binding (->where('col', '=', $value)) instead of escaping a literal, so PDO handles binary safely.
Sanitize/strip NUL bytes if the value should actually be text: str_replace("\0", '', $value).
Store binary data in a proper BLOB column and bind it as a stream/LOB.

Example fix

// before
$conn->escape(file_get_contents('/tmp/asset.bin'));

// after
$conn->escape(file_get_contents('/tmp/asset.bin'), true);

Defensive patterns

Strategy: validation

Validate before calling

if (is_string($value) && str_contains($value, "\0")) {
    $escaped = $connection->escape($value, true); // binary path
} else {
    $escaped = $connection->escape($value);
}

Type guard

function isBinaryString(string $value): bool {
    return str_contains($value, "\0") || mb_check_encoding($value, 'UTF-8') === false;
}

Try / catch

try {
    $sql = $connection->escape($value);
} catch (\RuntimeException $e) {
    if (str_contains($e->getMessage(), 'null bytes')) {
        $sql = $connection->escape($value, true);
    } else { throw $e; }
}

Prevention

When handling file/blob output, always pass $binary=true to escape().
Prefer parameter binding over literal escaping for binary data.
Sanitize text inputs to remove NUL bytes when they are unexpected.

When it happens

Trigger: Calling $connection->escape($s) where $s contains a NUL byte (\0 / chr(0)); reading a blob/binary file into a string and passing it to escape without $binary=true; binding raw bytes into a raw query fragment.

Common situations: Storing image/PDF/encrypted bytes in a column; reading from fread()/file_get_contents() of a binary file; serialized/compressed payloads that include NUL bytes.

Related errors

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

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