Error: F_JG219A: TLS Generic Error

Issue

The following error appears:

Error: F_JG219A: Protocol Violating EOF Error

Environment

• HVR 6
• High-Volume Agent (HVA)
• Operating system: any

Cause

F_JG219A error could also be from F_JG2537 during TLS negotiate, or from F_JG2199 during write. The key info is the Protocol violating EOF. This error means that the TCP socket did a clean shutdown, but there was no teardown of the TLS. It could come out of various places, the TLS negotiate, read, write, close, etc.

Possible causes: This issue occurs during the TLS negotiation, read, write, or close operations when the TCP socket closes cleanly, but the TLS session isn't properly shut down. This may happen for the following reasons:

• The agent process crashes before it can report an error.
• Network infrastructure, such as a router, firewall, or proxy, closes the socket unexpectedly.

In these scenarios, the operating system typically reports a F_JG057F: Connection Reset by Peer error. However, SSH tunnels, poorly implemented hardware, or proxies that try to break TLS connections may close the connection in a way that results in the above, generic error.

HVA-specific causes

For HVA environments, this issue may also occur for any of the following reasons:

• The Donkey closes the local loopback socket.
• Issues with the SSH tunnel or your SSH bastion host (if applicable).
• Issues with the Fivetran Proxy, including the proxy client, server, or agent (if applicable).
• Network infrastructure that closes without sending the proper send reset packets.

If a connection reset occurs on the agent side, the SSH tunnel may hide the underlying socket error from the hub. Instead of seeing the reset, the hub may only receive the generic error described above.

Resolution

General

TLS communication can pass through multiple network components between the hub and the agent, and errors can originate at any point. When a TCP connection closes without a proper TLS shutdown, HVR may only report a generic protocol error. When this happens, we may not provide more specific error details because:

• The socket may no longer exist when the error is detected.
• Additional details can't be logged for security reasons. To troubleshoot, collect and review log files from both the hub and the agent.

HVA-specific resolution

In HVA environments, particularly those using Fivetran Proxy, network traffic may use multiple tunneling layers, such as SSH or WebSockets. These operate at the TCP layer. If a network error occurs between the final cloud hop and the agent (for example, a connection reset), the SSH tunnel may hide the socket error from the hub. As a result, the hub may only report a generic EOF-related TLS error.

Steps to execute

HVR supports both TCP-level and application-level keepalive mechanisms to help prevent idle network connections from being closed. To reduce idle connection timeouts, set the following environment variables:

• HVR_TCP_KEEPALIVE: Enables TCP keepalive at the operating system level. HVR sets aggressive TCP keepalives between the hub and the agent, but these may not work reliably on modern internet networks or through load balancers.
• HVR_REMOTE_KEEPALIVE: Enables application-level keepalive. The agent spawns a transparent proxy process that sends empty HVR protocol messages at a configurable interval to ensure bytes flow over the socket.

Set HVR_TCP_KEEPALIVE on both hub and agent machines, and set HVR_REMOTE_KEEPALIVE on agent machines only. You must restart affected processes for changes to take effect.

HVR_TCP_KEEPALIVE

The HVR_TCP_KEEPALIVE variable enables TCP-level keepalive probes at the operating system layer. You can set the following values:

• -1: Disables TCP keepalive.
• 0: Enables using OS defaults. For example, the Linux default is 7200s (2h).
• >0: Enables with a custom interval in s.

Behavior

In this example, the keepalive interval is set to 600 seconds. TCP keepalive packets are sent as follows:

• The first probe is sent after 300s (half of the configured interval).
• The remaining 300s are divided into 30s intervals, during which probes are sent at equal intervals.
• Total number of probes sent: 10.

Limitations

• May not work through load balancers that don't forward TCP keepalive packets.
• May be ineffective through SSH tunnels or proxies.
• Some network devices drop keepalive traffic.

Recommended use

• Direct hub-to-agent connections.
• Simple networks without intermediate load balancers or proxies.

HVR_REMOTE_KEEPALIVE

HVR_REMOTE_KEEPALIVE enables application-level keepalive by sending periodic HVR protocol messages to keep connections alive through load balancers and proxies. You can set the following values:

• 0: Disable remote keepalive.
• >0: Enable with custom interval in seconds (s).

Behavior

• The Agent reads the Remote_Keepalive property.
• A transparent proxy process is created on hub connection.
• The proxy sends a minimal 4-byte HVR protocol message at the configured interval.
• This traffic resets idle timeouts on intermediate devices.

Recommended use

• Cloud load balancers, such as AWS ELB, Azure LB, GCP, LB.
• SSH tunnels or Fivetran Proxy.
• Networks with aggressive idle timeouts.
• Repeated F_JG219A: TLS read error: Protocol violating EOF errors.
• Multiple channels failing simultaneously.

Not recommended

• Simple local networks.
• Direct hub-to-agent connections without idle timeout issues.