Resolving Git Error: RPC Failed; curl 56 GnuTLS recv error (-12): A TLS Fatal Alert Has Been Received

Problem Background and Error Analysis

When executing git push origin master on Ubuntu 16.04 systems, users frequently encounter the following error message:

error: RPC failed; curl 56 GnuTLS recv error (-12): A TLS fatal alert has been received.
fatal: The remote end hung up unexpectedly
fatal: The remote end hung up unexpectedly
Everything up-to-date

This error indicates a serious issue during the TLS (Transport Layer Security) handshake process when Git communicates with remote repositories via HTTP/HTTPS protocols. The error code -12 corresponds to a specific failure state in the GnuTLS library, typically related to cipher suite negotiation, certificate verification, or network transmission stability.

Core Solution: Rebuilding Git with OpenSSL

Through practical verification, the most effective solution is to recompile Git, switching its dependent TLS library from GnuTLS to OpenSSL. Below are the detailed implementation steps:

First, uninstall the currently installed Git version:

sudo apt remove git
git --version  # Verify uninstallation

Install dependencies required for compilation:

sudo apt update
sudo apt install make libssl-dev libcurl4-openssl-dev libexpat1-dev gettext libz-dev autoconf

Download Git source code and compile:

wget https://github.com/git/git/archive/v2.25.1.tar.gz
tar -xzf v2.25.1.tar.gz
cd git-2.25.1
make configure
./configure --with-openssl  # Key configuration: specify OpenSSL usage
make -j$(nproc)
sudo make install

Verify the installation result:

git --version
ldd $(which git) | grep ssl  # Confirm linking to OpenSSL libraries

This method fundamentally resolves the compatibility issues between GnuTLS and certain server TLS implementations. OpenSSL, as a more widely used cryptography library, offers better protocol compatibility and stability.

Supplementary Solutions

In addition to the core rebuilding method, several other strategies are available for different scenarios:

Increasing HTTP POST Buffer

When the error is caused by large data transfers, try increasing Git's HTTP POST buffer:

git config --global http.postBuffer 1048576000
git config --global https.postBuffer 1048576000

This sets the buffer size to approximately 1GB, suitable for push operations on large repositories. However, this approach only alleviates transmission issues and cannot resolve fundamental TLS protocol conflicts.

Installing GnuTLS Toolkit

In some cases, the GnuTLS library itself might lack necessary components:

sudo apt install gnutls-bin

This provides a complete GnuTLS toolchain for the system, potentially fixing TLS handshake failures caused by incomplete library files.

Using Shallow Clone Strategy

For historical transfer issues in large repositories, employ shallow operations to reduce data volume:

git clone repo --depth=1
git pull --depth=1

This method only fetches recent commit records, significantly reducing transmission load. As a temporary solution, it cannot retrieve complete history and may impact subsequent development work.

In-depth Technical Principle Analysis

From a technical perspective, this error involves several key components:

TLS Protocol Handshake Process: When a Git client establishes an HTTPS connection with a server, it must complete the TLS handshake, including protocol version negotiation, cipher suite selection, and certificate verification. Compatibility issues between GnuTLS and certain server TLS implementations cause handshake failures.

cURL Library Integration: Git uses libcurl to handle HTTP/HTTPS communication, and cURL can be configured to use different TLS backends. In Ubuntu systems, the default compiled Git typically links to GnuTLS, while other systems might use OpenSSL or Schannel.

Network Transmission Mechanism: Git's smart HTTP protocol uses POST requests to transfer data. When packets are too large or the network is unstable, transmission timeouts or buffer overflows may occur, leading to connection interruptions.

Solution Comparison and Selection Recommendations

Comprehensive evaluation of various solutions:

Rebuilding Git with OpenSSL: As a fundamental solution, it completely eliminates GnuTLS compatibility issues and is recommended as the primary approach. Although compilation and installation are required, it provides a permanent fix.

Buffer Adjustment: Suitable for scenarios with poor network environments or extremely large repositories, effective as a temporary mitigation measure.

GnuTLS Toolkit Installation: Addresses simple problems caused by missing dependencies, quick to implement but with limited effectiveness.

Shallow Operations: An emergency solution for specific scenarios, not suitable for regular development workflows.

Developers should choose the most appropriate solution based on their specific environment. On Ubuntu 16.04 and similar systems, rebuilding Git with OpenSSL is the most reliable long-term solution.