The AES encryption/decryption function received a key derivation function (KDF) option array whose size is outside the allowed byte range.
MySQL error 3238 ER_AES_INVALID_KDF_OPTION_SIZE appears when AES_ENCRYPT or AES_DECRYPT receives a KDF option array that is not 0-255 bytes long. Pass a NULL value or a valid-length binary string to resolve the error.
ER_AES_INVALID_KDF_OPTION_SIZE
MySQL raises error code 3238 when AES_ENCRYPT or AES_DECRYPT is called with a key derivation function (KDF) option array whose byte length falls outside the permitted 0-255 range. The server rejects the call to protect cryptographic integrity.
The error was introduced in MySQL 5.7.40 and persists in 8.x. It has SQL state HY000 (general error).
AES_ENCRYPT and AES_DECRYPT can accept an optional BLOB that supplies KDF parameters such as iterations or salt. The array must fit within a single byte length field (0-255). Larger values break the internal parser and could weaken encryption, so MySQL blocks them.
Passing NULL disables custom KDF processing. Any non-NULL value is strictly validated.
Incorrect byte length in the kdf_options argument triggers the error. Common mistakes include passing a huge VARBINARY, forgetting to truncate hex literals, and supplying JSON or text instead of raw binary.
Using client libraries that double-encode or base64-encode the options can inflate size beyond 255 bytes.
Validate the length of the kdf_options parameter before calling AES_ENCRYPT or AES_DECRYPT. Ensure it is NULL or ≤255 bytes. Use OCTET_LENGTH() to confirm size inside MySQL.
Cast string literals with UNHEX or substring large blobs to the correct size. When options are unnecessary, pass NULL explicitly.
Bulk migration scripts often copy large blobs into kdf_options by mistake. Update the script to pass NULL or a trimmed VARBINARY.
ODBC or ORM layers may send base64 values. Decode them in the client so the raw binary fits the limit.
Add CHECK(OCTET_LENGTH(kdf_options)<=255) constraints if kdf_options is stored in a table.
Wrap AES calls in stored functions that validate size before execution. Galaxy users can save endorsed snippets that perform this guard check, preventing future misuse.
ER_AES_INVALID_KDF_OPTION_KEY (3239) signals an invalid key in the KDF option array. ER_AES_INVALID_ARG_VALUE (3237) indicates out-of-range mode or padding values. The fixes follow the same principle: validate inputs before encryption calls.
Hard-coded hex or binary string exceeds 255 bytes and is passed directly to AES_ENCRYPT.
Client library encodes options in base64 or JSON, inflating length beyond the limit.
Migrations map a large blob column to the kdf_options argument instead of the intended key or IV.
Raised when mode, padding, or iteration values are outside valid ranges.
Occurs if the option array contains an unsupported key identifier.
Signals malformed KDF option data that cannot be parsed.
No. It is a protective check. Fixing the size restores normal encryption without weakening security.
0 to 255 bytes inclusive.
No. The server always validates input to prevent misuse.
Galaxy snippets can embed OCTET_LENGTH checks, and the editor highlights errors before execution, reducing runtime failures.
.avif)
.avif){kind=logo}
