Linux SFTP Connection Error Fix

In this tutorial, you'll learn about Linux SFTP Connection Error Fix. We cover key concepts, practical examples, and best practices.

SFTP connections fail with errors like "Couldn't read packet: Connection reset by peer", "Received message too long", or "subsystem request failed on channel 0". These occur when the SSH server has restrictive configurations, the SFTP subsystem is disabled, or shell startup scripts produce output.

The Problem

sftp user@server

Error:

Received message too long 1234567890

Or:

Couldn't read packet: Connection reset by peer

Wrong Approach

# WRONG — sftp with no debugging output
sftp user@server

# WRONG — modifying subsystem without understanding the cause
sudo sed -i 's/Subsystem sftp/#Subsystem sftp/' /etc/ssh/sshd_config

Right Approach

# Debug the connection
sftp -v user@server

Expected output of a successful connection:

Connected to server.
sftp>

Step-by-Step Fix

Step 1: Check SSH connectivity first

ssh user@server echo "SSH works"

Step 2: Verify the SFTP subsystem

ssh user@server "grep sftp /etc/ssh/sshd_config"

Expected:

Subsystem sftp /usr/lib/openssh/sftp-server

Step 3: Fix "Received message too long"

This occurs when shell startup scripts (.bashrc, .profile) produce output.

# Check for echo statements in startup scripts
ssh user@server "cat ~/.bashrc ~/.profile 2>/dev/null | grep -n echo"

# Fix by removing non-interactive output
ssh user@server 'sed -i "/^echo/d" ~/.bashrc'

Step 4: Fix internal-sftp configuration

# Edit /etc/ssh/sshd_config
Subsystem sftp internal-sftp

# For chroot jails
Match Group sftp
ChrootDirectory /home/%u
ForceCommand internal-sftp
X11Forwarding no
AllowTcpForwarding no

Step 5: Restart SSH and test

sudo systemctl restart sshd
sftp user@server

Step 6: Check firewall and SELinux

sudo firewall-cmd --list-all
sudo ausearch -m avc -ts recent | grep sftp

Prevention Tips

• Keep shell startup scripts silent in non-interactive mode
• Use internal-sftp instead of sftp-server for better chroot support
• Never put echo or interactive commands in .bashrc or .profile
• Test SFTP immediately after SSH configuration changes
• Restrict SFTP users to specific directories with ChrootDirectory

Common Mistakes with sftp connection

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world LINUX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ