MySQL max_allowed_packet Size Exceeded on BLOB/TEXT Data

Large BLOB/TEXT data specifically tends to hit max_allowed_packet limits more often than typical row data, simply because these column types are exactly the ones designed to hold genuinely large content — images, documents, large JSON payloads — and the packet size limit needs to accommodate the largest single piece of such content your application actually handles.

The Problem

Inserting or retrieving a row with a large BLOB or TEXT value fails:

ERROR 2006 (HY000): MySQL server has gone away

ERROR 1153 (08S01): Got a packet bigger than 'max_allowed_packet' bytes

Smaller values in the same column, or the same operation against a different row with smaller content, work fine — directly pointing at the specific large value's size as the relevant factor.

Why It Happens

max_allowed_packet caps the maximum size of any single communication packet between client and server — and since a large BLOB/TEXT value effectively needs to travel as part of a single packet during insert or retrieval, a sufficiently large piece of content directly exceeds whatever the current limit is configured to. This is a straightforward, common consequence of working with genuinely large binary or text content, not a bug — MySQL's default packet size (commonly 4MB or so, depending on version) is a reasonable general default but often too small for applications specifically designed to store large files or documents directly in the database.

The Fix

First, determine the actual size of your largest expected BLOB/TEXT content, so you can size the limit appropriately rather than guessing:

SELECT MAX(LENGTH(document_data)) FROM documents;

Set max_allowed_packet comfortably above this actual maximum, on the server side:

SET GLOBAL max_allowed_packet = 268435456; -- 256MB, adjust to your actual needs

For a permanent configuration surviving a server restart, also set it in your MySQL configuration file:

# my.cnf
[mysqld]
max_allowed_packet = 256M

Critically, also set the matching client-side configuration, since a client-side default smaller than the server's configured value can still trigger this error even after correctly raising the server-side setting:

# my.cnf
[client]
max_allowed_packet = 256M

[mysqldump]
max_allowed_packet = 256M

For application code connecting via a specific database driver or library, check whether that library imposes its own separate packet size configuration independent of MySQL's own configuration files — many drivers have their own connection-level settings that also need adjustment:

# Example: Python mysql-connector
connection = mysql.connector.connect(
    host='localhost',
    max_allowed_packet=268435456,
)

Consider whether storing genuinely very large binary content (large images, videos, large documents) directly in the database is actually the right architectural choice at all, versus storing the content in dedicated object storage (like S3 or an equivalent) and keeping only a reference/URL in the database — this is a common, well-established pattern specifically because it avoids ever needing to push the database's packet size limits to accommodate content that databases aren't necessarily optimized to store and serve efficiently at scale in the first place:

CREATE TABLE documents (
    id INT PRIMARY KEY AUTO_INCREMENT,
    storage_url VARCHAR(500),  -- reference to object storage, not the content itself
    file_size BIGINT,
    uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

This architectural shift isn't always practical or necessary for every use case, but it's worth genuinely considering when you find yourself repeatedly raising max_allowed_packet to accommodate growing content sizes, since it addresses the underlying scalability concern more fundamentally than continuing to increase a configuration limit indefinitely as your largest stored objects keep growing over time.

Still Not Working?

If you've raised max_allowed_packet on both client and server but still encounter the error for specific operations, check whether a connection pooler, proxy, or load balancer sitting between your application and MySQL has its own separate, smaller packet or message size limit — tools like ProxySQL or certain cloud database proxy layers impose limits independent of MySQL's own configuration, and increasing MySQL's setting alone doesn't help if an intermediate layer enforces a smaller limit of its own, requiring that specific intermediary's own configuration to also be adjusted to match your actual largest content size.