Jitterbit private agent troubleshooting

Introduction

This page gives troubleshooting advice for various problems that may be encountered when running a private agent. Contact Jitterbit support for issues not listed here.

Jitterbit private agent not running or is stopped or unreachable

The "Agent Not Running or Unreachable" error message can be caused by these factors:

• You are on an older version of the agent.

  • Solution: Upgrade to the latest version of the agent.

• The Jitterbit Services are not running.

  • Solution: Services can be started in %windir%\system32\services.msc; OR

  

  

  • Solution: In the install directory you will find a StartServices.bat script that will start the relevant services; OR

  

  • Solution: For Windows, you will find an option to Start Jitterbit Services in the Start Menu.

  

  • Usually, if a service is not starting, you will find an error during the restart.

    • For Windows: Look for an error in C:\Program Files (x86)\Jitterbit Agent\log. Ensure they are running as Local System and check the Event Log for any error message.

    • For Linux: Look for an error in /opt/jitterbit/log.

    Note

    Replace USERNAME with your current username.

    Permissions: The account that the Jitterbit Services are running under needs to be a Local Administrator on the computer and have Full Access to the Jitterbit folder.

• Services are running but not able to communicate with Jitterbit Cloud.

  • Solution: Check:

    • If the Internet is working.

    • The log file, to see if there is an obvious error message:

      • For Windows: C:\Program Files (x86)\Jitterbit Agent\log\jitterbit-agent.log.

      • For Linux: /opt/jitterbit/log/jitterbit-agent.log.

• Proxy problems can also cause the Agent Not Running or Unreachable error message. Troubleshooting this, is a little more difficult, as there are so many different network configurations.

  • Solution: During install, you may have to check or uncheck the Negotiate Ntlm Proxy. This depends on which proxy you have. It is also very helpful to see the Denied Log from the Proxy Server.

Jitterbit private agent showing different versions or IPs

Issue

The Agents page in the Management Console may display different versions and/or IPs for a private agent. After restarting agent services, the Agents page may initially display the "correct" version/IP and then revert to continually cycle back and forth.

Cause of the issue

The agent server was likely cloned. The cloned server is running in parallel and collides with the main agent server. You cannot run multiple servers under the same agent credentials.

Steps to troubleshoot and resolve

1. Turn off the main server machine running the official version, wait for 10 minutes, and then refresh the Management Console Agents page. If the status of the agent switched from stopped to running, this means there is another instance of the agent running. The agents are either working alternately or simultaneously.

2. To resolve the issue, it will be necessary to find the instance running under the old version and turn that server off.

3. If you cannot do that, uninstall the official agent, create a new agent with a different name, and install it on the official server.

4. Verify the new agent is running, as listed on the Agents page in the Management Console.

5. Delete the old agent from the Agents page using the Action dropdown > Remove.

Connection, websocket, and I/O errors on Jitterbit private agents using Azure VMs

Overview

This page provides instructions on troubleshooting a Linux or Windows private agent installed on a Microsoft Azure virtual machine (VM). (See Private agent performance tuning for general performance tuning information.)

Troubleshoot lost connections

When using a private agent installed on a Microsoft Azure VM, you may experience lost connections. Azure sets the WebSocket idle timeout to 4 minutes, while the private agent default to ping Harmony is set to 5 minutes. To resolve this issue, reduce the interval for the agent heartbeat:

1. Open the jitterbit-agent-config.properties file in a text editor. This file can be found in these directories:

   • Linux: <JITTERBIT_HOME>/Resources/

   • Windows: C:\Program Files\Jitterbit Agent\Resources

2. Find the agent.heart.beat.interval setting:

   #Agent heart beat interval (IN MINUTES)
   agent.heart.beat.interval=5
   

3. Change the setting to agent.heart.beat.interval=3.

4. Save the changes and restart the agent.

Troubleshoot websocket and I/O errors

Errors related to WebSocket and I/O can be resolved with updates to the VM's associated IP idle timeout, network address translation (NAT) gateway TCP idle timeout, and virtual network (VNET) flow timeout settings.

The IP idle timeout, NAT gateway TCP idle timeout, and VNET flow timeout values all must be set to 15 minutes.

Identify relevant errors

WebSocket and I/O errors can be identified by referencing the operation logs and the jitterbit-agent.log file. This log file can be found in one of the following locations:

• For Windows: C:\Program Files (x86)\Jitterbit Agent\log\jitterbit-agent.log.

• For Linux: /opt/jitterbit/log/jitterbit-agent.log.

Operation log errors

If present, any of the following messages in the operation log details for an operation with an Error status can be indicative of a WebSocket or I/O error:

The operation "Example Operation" completed successfully.

No message found while removing message in cache for: Message Info: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Message Version (Agent): XXXX Message Version (Harmony): XXX Counter (Harmony): 1 Submitted Timestamp (Harmony):2024-01-20 11:55:00.700 , message will be retried later OperationInstanceGUID: XXX

Run message could not reach the agent.

Agent log file errors

If present, any of the following messages in the jitterbit-agent.log file can be indicative of a WebSocket or I/O error:

2024-01-20 12:00:00 request handler thread #10642  INFO org.jitterbit.integration.server.api.util.AgentRetryExecutor:53 - Agent Message Receipt (OperationInstanceGUID: XXX) failed. Retrying....
2024-01-20 12:00:00 request handler thread #10642 ERROR org.jitterbit.integration.server.api.util.AgentRetryExecutor:55 - org.springframework.web.client.ResourceAccessException: I/O error on PUT request for "https://na-east.jitterbit.com/jitterbit-cloud-restful-service/agent/ackmsgreceipt": Read timed out; nested exception is java.net.SocketTimeoutException: Read timed out

E:2024-01-20 12:00:00 request handler thread #884 ERROR org.jitterbit.integration.server.messaging.agent.listener.AgentMessageListener:231 - No message found while removing message in cache for: Message Info: AgentId: 000001 AgentGroupId: 000001 MessageId: XXX Message Version (Agent): XXXX Message Version (Harmony): XXX Counter (Harmony): 1 Submitted Timestamp (Harmony):2024-01-20 11:55:00.700 , message will be retried later OperationInstanceGUID: XXX

Drain stop the agent

Drain stop the agent before updating any timeout settings. If you have more than one agent in the affected agent group, do the same for all of them.

Isolate agent resources

It is recommended that the agent's VM and its associated resources are separated into their own resource group in Azure. This includes its VNET, IP, NAT gateway, network interface (NIC), and network security group (NSG), if present.

Update the IP's idle timeout

1. In the Azure portal, navigate to the resource group associated with the agent's VM.

2. Identify and click the IP item associated with the VM:

   

3. Click Configuration and change the Idle timeout (minutes) value to 15 minutes:

   

Update the NAT gateway's TCP idle timeout

1. In the Azure portal, navigate to the resource group associated with the agent's VM.

2. Identify and click the NAT gateway item associated with the VM and IP, if present. An associated NAT gateway will also be listed in the IP item's Overview next to the Associated to field.

3. Click Configuration and change the TCP idle timeout (minutes) value to 15 minutes.

Update the VNET's flow timeout

1. In the Azure portal, navigate to the resource group associated with the agent's VM.

2. Identify and click the VNET item associated with the VM:

   

3. In Overview, click Configure next to Flow timeout:

   

4. In the Flow timeout pane, enable the Enable flow timeout setting and change the Flow timeout (minutes) value to 15 minutes:

   

5. Click Save.

Restart the agent

1. In the Azure portal, restart the agent's VM.

2. Restart the stopped agent. See either Restart a Windows agent or Restart a Linux agent for detailed information.

Error 1722 with Windows Jitterbit private agents

Issue

The Windows private agent installation fails with this error message:

Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. ...

Cause and resolution of the issue

There are multiple reasons the private agent installation could fail with this error message. Two of the most common reasons are a conflict with the Microsoft Visual C++ Redistributable or having unallowed characters in the PostgreSQL password.

Microsoft Visual C++ Redistributable

A conflict with an existing version of Microsoft Visual C++ Redistributable can cause Error 1722.

Private agents require Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 to be installed before installing a private agent. Microsoft includes the same redistributable files for Visual Studio C++ 2015, 2017, and 2019. Install the 64-bit Windows version using vc_redist.x64.exe.

Unallowed PostgreSQL password characters

A PostgreSQL password that uses unallowed characters can cause Error 1722.

To resolve this issue, do not use a plus sign (+) as part of the PostgreSQL password when installing a private agent. The minimum number of characters for a PostgreSQL password is eight (8). We recommend that you not use accented characters (such as é) or any of these characters in the PostgreSQL password: + @ $ % & [] {} () , ; ? ^ = £.

IPv6 issue on Windows Jitterbit private agents

Overview

Some customers have experienced issues when Internet Protocol version 6 (IPv6) is enabled. In these instances, we recommend disabling IPv6 and IP Helper.

Disable IPv6

To disable IPv6:

1. On Windows, open Control Panel > Network and Internet > Network Connections.

2. Open the Properties of a connection.

3. Clear the checkbox for Internet Protocol Version 6 (TCP/IPv6):

   

Disable IP helper

To disable IP Helper:

1. On Windows, open Services.

2. Locate IP Helper in the list of services. Then right-click on IP Helper and select Properties.

3. In the IP Helper Properties, click Stop to stop the service, and change the Startup type to Disabled:

   

Apache Server error on Jitterbit private agents

If you receive this error message:

No Installed ConfigArgs for the Service "Jitterbit Apache Server"

It means that the user that the Jitterbit Apache server is running under does not have full access to the Jitterbit folder.

PostgreSQL errors with Windows Jitterbit private agents

Issue

In certain cases, after uninstalling a Windows private agent and then attempting to reinstall the agent, users may receive an error related to the PostgreSQL database.

Cause of the issue

This error has been known to occur on systems where the PostgreSQL installation associated with the private agent has not been completely removed.

Resolution

To resolve the error, users should follow the steps described in Uninstall a Windows private agent to completely remove the Jitterbit PostgreSQL user account.

Once this is done, you should be able to complete a new agent installation. If you are still experiencing issues, please contact support.

Unable to install 64-bit Windows Jitterbit private agents with two-factor authentication (TFA)

Issue

It is a known issue that 64-bit Windows private agents cannot be installed with two-factor authentication (TFA) enabled. If TFA is active, installing a 64-bit Windows private agent will fail and present an error dialog.

Workaround

To work around this issue, temporarily disable TFA and install the 64-bit Windows private agent. After installation, enable TFA.

TFA can be disabled and enabled from an organization's settings accessed from the Management Console Organizations page.

Connection slots error with Windows 64-bit Jitterbit private agents

Issue

This error is known to occur with Windows 64-bit private agents installed prior to the Harmony 10.14 release:

Failed to connect to back-end database "TranDb"
FATAL: remaining connection slots are reserved for non-replication superuser
connections
(0) SQL Error! SQLSTATE = 53300 Native err = 210 msg = FATAL: remaining connection slots are reserved for non-replication superuser connections
(1) SQL Error! SQLSTATE = IM006 Native err = 0 msg = [Microsoft][ODBC Driver Manager] Driver's SQLSetConnectAttr failed
Details:
Unable to connect to database using connection string:
UID=jitterbit;PWD=<REMOVED>;SERVER=127.0.0.1;DRIVER={PostgreSQL ODBC
Driver(UNICODE)};DATABASE=TranDb;Port=6543;!

Resolution

To resolve this issue, increase the max_connections and checkpoint_timeout settings in the postgresql.conf file on the Windows 64-bit private agent following these steps:

1. Make a backup copy of your postgresql.conf file and save it to another location. This file can be found in the C:\Program Files\PostgreSQL\9.x\data directory.

2. Open the postgresql.conf file in a text editor.

3. Find the max_connections setting.

   # - Connection Settings -
   
   listen_addresses = '*'      # what IP address(es) to listen on;
                       # comma-separated list of addresses;
                       # defaults to 'localhost'; use '*' for all
                       # (change requires restart)
   port = 6543             # (change requires restart)
   max_connections = 100           # (change requires restart)
   #superuser_reserved_connections = 3 # (change requires restart)
   #unix_socket_directories = ''   # comma-separated list of directories
   

4. Change this setting to max_connections = 400.

5. Find the checkpoint_timeout setting.

   # - Checkpoints -
   
   #checkpoint_timeout = 5min      # range 30s-1d
   #max_wal_size = 1GB
   #min_wal_size = 80MB
   

6. Change this setting to checkpoint_timeout = 1h and delete the comment marker (#) the beginning of the line.

7. Save your changes and restart the agent.

Recover a failed private agent installation on Windows

Issue

Installation or upgrade of a private agent on Windows fails.

Resolution

Due to the number of possible causes, the simplest solution is to completely uninstall then reinstall the private agent software if any part of the installation or upgrade process fails.