Quick Fix: It's Usually the MTU
Roughly 90% of the time, this error stems from a network MTU (Maximum Transmission Unit) mismatch. When a packet exceeds the size limit of a network segment—common with VPNs, Docker bridges, or Cloud VPCs—it gets fragmented. SSL/TLS protocols cannot handle this fragmentation well, leading to checksum failures.
Immediate action: Drop the MTU on your network interface or Docker network to 1400 or 1450. Test it immediately to see if the connection stabilizes.
# Temporarily lower MTU to 1400 for testing
sudo ip link set dev eth0 mtu 1400
Why This Happens
This error signals a breakdown in data integrity. It means the data arriving at your client doesn't match the Message Authentication Code (MAC) generated by the server. Your data was likely corrupted, truncated, or reassembled incorrectly during transit.
SSL/TLS protocols are unforgiving when it comes to integrity. Even a single missing byte or a flipped bit within a packet will cause the decryption process to fail. Unlike a standard timeout, this error proves the connection was successful, but the data stream collapsed once heavy traffic began flowing.
Where things usually go wrong
- Docker Containers: Docker defaults to an MTU of 1500. However, if your host uses a lower MTU (like the 1460 standard on Google Cloud Platform), packets will be truncated at the bridge.
- VPNs and Encrypted Tunnels: Protocols such as IPsec or WireGuard wrap your data in extra headers. This leaves less than the standard 1500 bytes for the actual payload.
- Legacy Network Hardware: Occasionally, a failing switch or a cheap NIC will flip bits under high load.
- Library Mismatches: Incompatibilities between your database driver (like
libpq) and the system's OpenSSL version can cause erratic decryption behavior.
How to Fix It
1. Calibrate the MTU
Cloud environments and VPNs often require an MTU lower than the standard 1500 bytes. Check your current settings with ip addr. To find the exact limit your path supports, use ping with the "do not fragment" flag:
# Test with 1472 bytes (1500 - 28 bytes for ICMP/IP headers)
ping -M do -s 1472 your-database-host.com
If you see a "Frag needed" error, lower the -s value (try 1430, then 1400) until the ping succeeds. Add 28 to that successful value to determine your maximum MTU.
To persist this change on Ubuntu (using Netplan):
# /etc/netplan/01-netcfg.yaml
network:
version: 2
ethernets:
eth0:
mtu: 1400
2. Configure Docker Network MTU
If your application runs in Docker but connects to an external database, you must align the bridge MTU in your docker-compose.yml:
networks:
default:
driver: bridge
driver_opts:
com.docker.network.driver.mtu: 1400
3. Upgrade Client Libraries
Software bugs are sometimes the culprit. If you're running PostgreSQL, libpq handles the heavy SSL lifting. Upgrading your base image—for example, moving from python:3.9-slim to python:3.12-slim—often resolves deep-seated OpenSSL bugs.
sudo apt-get update && sudo apt-get install --only-upgrade libpq5 openssl
4. Disable NIC Hardware Offloading
On bare-metal servers, a Network Interface Card (NIC) might try to optimize TCP processing via Generic Receive Offload (GRO). Sometimes these optimizations mangle encrypted packets. Turn them off to rule out hardware interference:
sudo ethtool -K eth0 gro off
sudo ethtool -K eth0 lro off
Verifying the Fix
Small queries often succeed even with MTU issues because they don't hit the packet size limit. To truly test the connection, run a query that returns several thousand rows. This forces the network to handle large, fragmented payloads.
# Use psql to pull a large dataset
psql "sslmode=require host=your-db.com user=myuser dbname=mydb" -c "SELECT * FROM large_table LIMIT 5000;" > /dev/null
If this completes without a bad record mac error, your tunnel is finally stable.
Prevention and Networking Tips
A reliable database relies on a stable network foundation. When designing subnets or VPCs, always account for the overhead of security layers like IPsec.
I rely on tools like ToolCraft's Subnet Calculator to map out network boundaries. It helps visualize CIDR ranges and ensures subnetting logic doesn't conflict with VPN gateways that demand specific MTU adjustments. Planning these boundaries early prevents frustrating SSL handshake and decryption failures down the road.
Finally, inspect your firewall logs for "Deep Packet Inspection" (DPI) settings. Some enterprise firewalls attempt to inspect SSL traffic and accidentally corrupt the records, triggering this exact error message.