Git Clone/Fetch Freezing During SSH: Troubleshooting

Git clone or fetch operations freezing during SSH connections are typically caused by network timeouts, misconfigured SSH agents, or missing identity files. This issue often manifests as a hanging prompt with no error message, preventing developers from accessing remote repositories efficiently. By verifying your SSH configuration, testing connectivity manually, and ensuring proper key permissions, you can restore stable communication between your local machine and the Git server.

Understanding the Root Causes

When a Git command appears to freeze, it is usually waiting for a response that never arrives. This behavior differs from a connection refused error, which fails immediately. The most common culprits include firewall interference blocking port 22, incorrect SSH agent forwarding, or permission issues with private keys. Additionally, some corporate networks may throttle long-running TCP connections, causing the handshake to time out silently. It is also possible that the SSH client is attempting to use an incorrect identity file, leading to repeated authentication failures that appear as a hang rather than an explicit error.

Testing SSH Connectivity Manually

Before diving into complex Git configurations, verify that the underlying SSH connection works. Use the verbose mode of the SSH command to see exactly where the process stalls. Run the following command, replacing [email protected] with your specific Git host:

ssh -T [email protected]

If this command hangs, the issue is not with Git itself but with the network or SSH daemon. Check if your firewall allows outbound traffic on port 22. If you are behind a proxy, ensure that your environment variables like http_proxy and https_proxy are set correctly, although these do not affect raw SSH tunnels directly. You should see a message confirming successful authentication, such as "Hi username! You've successfully authenticated." If it fails, consult our guide on Git Ignoring Identity File Configuration: A Solution to ensure your keys are being recognized.

Configuring SSH for Stability

To prevent timeouts, you can adjust the SSH client settings by editing your ~/.ssh/config file. Adding specific parameters can help maintain the connection and reduce latency. For example, you can enable keep-alive messages to prevent intermediate firewalls from dropping idle connections.

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa
    ServerAliveInterval 60
    ServerAliveCountMax 3

The ServerAliveInterval sends a request to the server every 60 seconds, ensuring the connection remains active. The ServerAliveCountMax setting determines how many missed responses trigger a disconnect. Adjust these values based on your network stability. If you are using multiple keys, ensure the correct one is specified via IdentityFile. Refer to Git SSH: Passphrase Prompted Even After Caching Credentials if you suspect passphrase caching issues are contributing to delays.

Checking Git Remote URLs

Ensure that your repository is using the SSH URL rather than HTTPS. HTTPS connections might be blocked or throttled differently depending on your network policy. Verify your remote URL with:

git remote -v

If it shows an HTTPS link, change it to SSH using:

git remote set-url origin [email protected]:user/repo.git

SSH is generally more robust for large transfers and interactive sessions because it does not require re-authentication for every packet in the same way HTTPS might handle token refreshes. This switch alone resolves freezing issues for many users who were previously stuck on HTTP/HTTPS protocols.

Debugging Agent and Key Issues

Sometimes the SSH agent is overloaded or holding stale keys. Restarting the agent can clear temporary glitches. On Linux and macOS, you can kill the existing agent and start a new one:

eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa

On Windows, check the OpenSSH service or use Pageant if you are using PuTTY-based tools. Ensure that the private key has strict permissions; on Unix-like systems, it must be readable only by you (chmod 600 ~/.ssh/id_rsa). If permissions are too open, SSH will refuse to use the key, potentially causing a silent failure during the handshake phase.

Frequently Asked Questions

Why does git clone work initially but freeze later?

This often indicates a network timeout during the data transfer phase rather than the initial connection. Large repositories require sustained bandwidth, and unstable connections may drop packets without notifying the client immediately. Increasing the core.compression level or using a different network interface can help mitigate this.

How do I know if my firewall is blocking SSH?

If ssh -T git@host returns immediately with a connection refused error, the firewall is likely blocking port 22. However, if it hangs indefinitely, the firewall may be allowing the connection but dropping subsequent packets. Test by pinging the host or using telnet to port 22 to diagnose the exact point of failure.

Can I use HTTPS instead of SSH to avoid freezing?

Yes, switching to HTTPS can bypass SSH-specific issues, but it requires handling credentials differently. You may need to configure credential helpers or use Personal Access Tokens (PATs). While easier to set up, HTTPS can sometimes be slower for very large repositories due to lack of persistent connection optimization.

What should I do if my SSH key passphrase is not being cached?

Ensure your SSH agent is running and add your key using ssh-add. On macOS, adding -K to the ssh-add command caches the passphrase in the keychain. On Linux, consider using GNOME Keyring or KDE Wallet to automate this process securely.

Does Git have a built-in timeout setting for SSH?

Git itself does not control SSH timeouts directly; it relies on the underlying SSH client. You must configure timeouts in your ~/.ssh/config file using ServerAliveInterval and ConnectTimeout. Setting a lower ConnectTimeout can help fail fast if the server is unreachable.