Can't scp files with long/weird filenames: Invalid argument

Scp fails with an "Invalid argument" error for long or special-character filenames primarily because the destination filesystem (often FAT32/vFAT) rejects names exceeding 255 characters or containing invalid symbols. The most reliable solution is to compress files into a tar archive on the source, transfer the single archive via scp, and extract it at the destination. This bypasses filename length restrictions entirely.

Understanding the Root Cause

The "Invalid argument" (EINVAL) error in scp is rarely a network issue. It is almost always a filesystem constraint violation. When you transfer a file, scp creates the file on the remote host using the exact same name. If that name violates the rules of the target filesystem, the operating kernel rejects the system call. Common culprits include:

• FAT32/vFAT Limits: Many external drives and cloud storage mounts use vFAT. These filesystems have a strict 255-byte limit for filenames and do not allow certain characters like colons (:), asterisks (*), or question marks (?). They are also case-insensitive, which can cause conflicts.
• NTFS Quirks: While Linux can read NTFS, writing to it via smbclient or specific mount options may reject reserved Windows filenames like AUX, NUL, or CON.
• Ext4/XFS Constraints: These modern Linux filesystems support very long names (up to 255 bytes), but they do not allow null bytes (\0) within filenames. If your file contains binary data in its name, it will fail.

Detecting the Filesystem Type

Before attempting fixes, verify the filesystem type of your destination directory. Run the following command on the remote server:

df -T /path/to/destination

Look at the second column. If it says vfat, msdos, or ntfs, you are dealing with a filesystem that has stricter naming conventions than standard Linux ext4. If it says ext4 or xfs, the issue might be related to specific shell escaping errors rather than filesystem limits.

The Robust Solution: Using Tar Archives

The most effective way to bypass filename restrictions is to avoid sending individual files altogether. Instead, bundle them into a single archive. An archive file typically has a simple, short name that complies with all filesystem standards. Perform these steps on your local machine:

1. Create a tarball: Use tar to compress your problematic files. The -czf flags create a gzip-compressed archive. Replace output.tar.gz with your desired archive name and list the files or directories you want to transfer.

tar -czf output.tar.gz file1.txt "file with spaces.txt" weird_name*

• Transfer the archive: Now, use scp to move this single, safe file to the remote server.

scp output.tar.gz user@remote:/path/to/destination/

• Extract on the remote server: Log into the remote server and extract the contents. The extraction process reconstructs the original filenames, including any long or special characters, directly from the archive metadata.

ssh user@remote "tar -xzf /path/to/destination/output.tar.gz -C /path/to/destination/"

This method works regardless of whether the destination is vFAT, NTFS, or Ext4. It preserves permissions and timestamps if you add the -p flag to the tar commands. For more details on managing large transfers, see our guide on Accessing a Linux Server with Credentials Managed via PAM: Copying Files Remotely using SCP.

Alternative: Renaming Files Before Transfer

If you cannot use archives due to disk space constraints or workflow requirements, you must sanitize the filenames before transferring. This involves renaming files to remove invalid characters and truncate long names. You can automate this with a bash script. Here is a basic example that removes non-alphanumeric characters and truncates names to 100 characters:

for f in *; do
    newname=$(echo "$f" | tr -cd '[:alnum:]._-')
    if [ ${#newname} -gt 100 ]; then
        newname="${newname:0:100}"
    fi
    mv -- "$f" "$newname"
done

After running this script, your files will have clean, short names that scp can handle easily. Remember to rename them back after extraction if needed. This approach is useful when moving Windows files to Unix locations, as discussed in Moving Windows Drive Files to Unix Location: A Comprehensive Guide.

Why SSH Buffer Settings Do Not Help

Some users attempt to resolve this by increasing SSH buffer sizes or adjusting MaxPacketSize in sshd_config. This is incorrect. The "Invalid argument" error occurs during the file creation phase on the destination filesystem, not during data transmission. Network buffers have no influence on whether the kernel accepts a filename. Adjusting these settings wastes time and does not address the underlying filesystem incompatibility. Always prioritize the tar archive method for reliability.

Handling Special Characters in Filenames

Even on compatible filesystems, special characters can cause issues if not escaped properly in the shell. When typing filenames manually, always enclose them in quotes or escape spaces with backslashes.

scp "my file.txt" user@host:/dest/

scp my\ file.txt user@host:/dest/

If you are scripting, use find with -print0 and xargs -0 to handle filenames with newlines or spaces safely. This prevents the shell from misinterpreting parts of the filename as separate arguments.

Debugging Persistent Errors

If the tar method still fails, check the remote server's logs. Use tail -f /var/log/auth.log or /var/log/syslog while attempting the transfer. Look for messages indicating permission denied or disk full. Occasionally, "Invalid argument" can mask a lack of write permissions if the user does not own the target directory. Ensure you have write access to the destination folder using ls -ld /path/to/destination. For troubleshooting other common SCP failures, such as broken pipes, refer to our article on Broken Pipe Error During File Transfer via SCP on DigitalOcean Droplet.

Frequently Asked Questions

Can I increase the filename length limit on vFAT?

No, the 255-byte limit is hardcoded into the FAT32 specification and cannot be changed by mounting options. You must shorten the names or use an archive format to bypass this limitation entirely.

Does scp support unicode filenames natively?

Yes, modern versions of OpenSSH support UTF-8 filenames. However, the remote filesystem must also support UTF-8 encoding. If the destination is a legacy Windows share or old vFAT drive, unicode characters may be rejected or corrupted.

What if I only have one file with a bad name?

You can simply rename it locally before transferring. Use the mv command to change the filename to something simple, transfer it, and then rename it again on the remote server after copying.

Is rsync better than scp for this problem?

Rsync handles filenames similarly to scp; it will also fail with "Invalid argument" if the destination filesystem rejects the name. Switching tools does not solve the underlying filesystem constraint issue.

How do I check if a filename contains null bytes?

Use the find command with -name '*[^[:print:]]*' or inspect files with ls -b to show non-printable characters. Null bytes cannot exist in Linux filenames and will always cause transfer errors.