This client-side error occurs when a file path supplied to MySQL file operations exceeds operating system limits. Fix it by shortening file paths or restructuring directory hierarchies.
CR_FILE_NAME_TOO_LONG is a client-side error introduced in MySQL 8.0.1 that occurs when you attempt to use file operations with paths that exceed your operating system's length restrictions. Unlike server errors, this is caught by the MySQL client library before any server communication happens. The error most commonly appears during LOAD DATA INFILE, LOAD DATA LOCAL INFILE, or SELECT ... INTO OUTFILE operations where the full path to the input or output file is too long. Operating systems enforce strict limits on both individual file name components and total path lengths. Most Unix-based systems allow 255 bytes per path component (directory or file name) and up to 4,096 bytes for the entire absolute path. Windows typically limits paths to 260 characters (MAX_PATH). When these limits are exceeded, the MySQL client returns error 2063 immediately without attempting to contact the database server.
Check how long your file path actually is using shell commands:
# On Linux/macOS - count characters in path
echo -n "/your/very/long/path/to/file.csv" | wc -c
# Or use this to check the full absolute path
realpath /your/path/file.csv | wc -cMost Unix systems have a limit of 4,096 bytes for the full path. If your path is approaching or exceeding this limit, you've confirmed the issue.
The simplest fix is relocating your data file to a directory closer to the filesystem root:
# Create a short path directory
sudo mkdir -p /srv/mysql_data
# Move your file
sudo mv /very/long/nested/directory/structure/data/files/export.csv /srv/mysql_data/
# Update your MySQL query
# Before:
# SELECT * INTO OUTFILE '/very/long/nested/directory/structure/data/files/export.csv' FROM users;
# After:
SELECT * INTO OUTFILE '/srv/mysql_data/export.csv' FROM users;This immediately reduces path length and avoids the error.
If you cannot move files, change your working directory before running MySQL commands:
# Navigate to the data directory
cd /long/nested/path/to/data/directory
# Now use relative path in MySQL
mysql -u user -p database -e "LOAD DATA INFILE './file.csv' INTO TABLE users"Relative paths are resolved from the current directory, potentially creating much shorter effective paths.
Use symbolic links to create short aliases for deeply nested directories:
# Create symlink from short path to long directory
sudo ln -s /very/long/nested/directory/structure/data /data
# Now use the short symlink in MySQL
SELECT * INTO OUTFILE '/data/export.csv' FROM users;The symlink provides a shortcut without moving files or changing your directory structure.
If you control the directory structure, simplify naming conventions:
# Before: deeply nested with long names
/var/application/production/mysql_exports/2024_01_15_user_data_export/full_backup_with_timestamps/
# After: flattened with concise names
/var/mysql_out/2024-01-15/
# Avoid embedding UUIDs or long identifiers in paths
# Before: backup_a1b2c3d4-e5f6-7890-abcd-ef1234567890_final.csv
# After: backup_20240115.csvShorter component names accumulate significant savings in nested structures.
If the path is generated by application code, update configuration or path building logic:
// Before: deep nesting with verbose names
const exportPath = `${process.env.APP_ROOT}/data/exports/${year}/${month}/${day}/${userId}/${timestamp}/export.csv`;
// After: flatter structure with concise names
const exportPath = `/srv/mysql_out/${date}/${userId}.csv`;Configure your application to write files to a dedicated short path directory.
Why 2063 is client-side only: This error code was added in MySQL 8.0.1 and is enforced by the MySQL client library, not the server. The client checks path length against OS limits before sending any network request. This means the error appears instantly and never reaches server logs.
Platform-specific limits: Unix systems typically support 255 bytes per path component and 4,096 bytes total path length. Windows has a default MAX_PATH limit of 260 characters, though this can be extended to 32,767 characters with long path support enabled (requires Windows 10 version 1607 or later and application manifest changes).
Character encoding considerations: Path length limits are typically measured in bytes, not characters. Multi-byte UTF-8 characters count as multiple bytes, so paths with international characters may hit limits sooner than expected. For example, a file name with 200 Chinese characters could exceed the 255-byte component limit.
Temporary file workarounds: Some applications work around this by writing to a temporary short path first, then moving the file to its final destination after the MySQL operation completes. This keeps MySQL operations in compliant paths while allowing your application to maintain its directory structure.
Docker and container environments: Containers may introduce additional path nesting (e.g., /var/lib/docker/volumes/...). When mounting volumes, prefer bind mounts to short host paths rather than named volumes that create deep hierarchies.
No configuration override: Unlike some MySQL limits that can be adjusted with server variables, path length restrictions are pure OS constraints with no MySQL-level override. The only solution is to shorten paths at the filesystem level.
EE_WRITE (3): Error writing file
How to fix "EE_WRITE (3): Error writing file" in MySQL
CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters
How to fix "CR_PARAMS_NOT_BOUND (2031): No data supplied for parameters" in MySQL
CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed
How to fix "CR_DNS_SRV_LOOKUP_FAILED (2070): DNS SRV lookup failed" in MySQL
ERROR 1146: Table 'database.table' doesn't exist
How to fix "ERROR 1146: Table doesn't exist" in MySQL
ERROR 1040: Too many connections
How to fix "ERROR 1040: Too many connections" in MySQL