On-premise agents: Troubleshooting and FAQs

Follow this checklist to ensure that the on-premise agent's base configurations are correct. If you've completed the checklist and your agent isn't working as expected, continue to follow the troubleshooting steps in this article.

• Verify the agent's status

  1. In integrator.io, go to Resources, and then select On-premise agents.
  2. Determine if the agent is Online (green) or Offline (red). If the agent is offline, note the last check-in time.
  3. Note the Last heartbeat timestamp — it should be recent if the agent is live.
• Confirm that the agent is running locally Windows:

  1. Press Win + R, type services.msc, and press Enter.
  2. Locate Celigo Agent in the list.
  3. Validate that the agent's Status is 'Running' and the Startup type is 'Automatic'.

  – OR – 

  1. Navigate to Task Manager > Processes.
  2. Verify that agent-windows.exe is running.

  Linux: Run the following command: systemctl status celigo-agent. The status should be 'Active (running)'.

• Check your network connectivity 

  1. Test your network's outbound access to https://api.integrator.io using the following curl command: curl -I https://api.integrator.io.
  2. Confirm that your firewall allows outbound port 443 (HTTPS). If your firewall is behind a proxy:
     1. Windows: Check Internet Options > Connections > LAN settings.
     2. Linux: Check the following environment variables: HTTP_PROXY and HTTPS_PROXY
• Verify the agent's token configuration: You must verify that the agent's token in your on-premise server and integrator.io are identical. Windows:

  1. In your Windows server, navigate to C:\Users\<user>\AppData\Roaming\Agent\ and open the Settings file.
  2. Note the agent's token.
  3. In your browser, navigate to integrator.io and sign in.
  4. Go to Resources, and then select On-premise agents. Select Show token for the agent.
  5. Compare the agent tokens.

  Linux:

  1. Execute the sudo cat /root/.config/agent/Settings command.
  2. Search the Settings file for the agent's token.
  3. In your browser, navigate to integrator.io and sign in.
  4. Go to Resources, and then select On-premise agents. Select Show token for the agent.
  5. Compare the agent tokens.
• Confirm your agent's version Windows:

  1. In your server, navigate to Control Panel > Programs > Programs and Features.
  2. Find Celigo Agent in the list.

  3. Your agent version must be 4.6.0 or later. If you haven't updated your agent, it isn't receiving automatic updates, which may be causing your issues.

     Exception: Celigo has ended support for users running Windows Server 2012 R2 with the Celigo on-premise agent. If your server is on this Windows version, you must download agent version 4.3.0. Failure to do so will trigger automatic updates that will break your on-premise agent configuration and cause your flows to fail. Note that version 4.3.0 does not support automatic updates since Celigo has ended support for Windows Server 2012 R2.

  Linux: If you're using the packaged version, run: sudo find / -type f -name "*.log" 2>/dev/null | sudo xargs grep -i "latest version" 2>/dev/null. If not, check the version in the Linux agent logs by running: journalctl -u celigoagent.service -n 1000 -f.

• Validate connection settings In integrator.io, open a connection that uses the agent and verify the following:

  • Your connection is using the correct agent.
  • The Base URI is reachable from the agent host (for example, localhost or the target system's IP address).
• Review logs (optional for early signs) Follow the steps below to inspect the agent logs in either Windows or Linux operating systems. If the logs are not available, check for missing or empty log files. Windows:

  1. Open the Celigo Agent in your Windows server.
  2. Select View logs.
  3. Search for:
     1. Connection errors
     2. Authentication failures
     3. Unexpected restarts or shutdowns

  – OR – 

  1. Navigate to C:\Users\<user>\AppData\Roaming\Agent\.
  2. Search for server-{{Current Date timestamp}} and open the corresponding file.
  3. In the logs, search for:
     1. Connection errors
     2. Authentication failures
     3. Unexpected restarts or shutdowns

  Linux:

  1. Open your terminal.
  2. Run journalctl -u celigoagent.service -f.
  3. Review the logs for:
     1. Connection errors
     2. Authentication failures
     3. Unexpected restarts or shutdowns

  To review a large number of older logs, use journalctl -u celigoagent.service -n 1000 -f. You can increase and decrease the number "1000" to retrieve more or less log data.

• Verify system resources: Ensure the host meets requirements.

  • 2–4 GB RAM minimum
  • 2 CPU cores
  • 64-bit OS

  Windows:

  1. Navigate to Task Manager > Performance.
  2. Check the agent's CPU and RAM usage to determine if it's performance is degraded.
  3. Make sure no other heavy processes are affecting the agent.

  Linux:

  • Run the top free -m command to verify the agent's CPU and RAM usage.

Once these checks are complete, if the issue persists, move on to targeted troubleshooting steps (for example, connection errors, failed flow execution, network misconfigurations).

In some cases, deleting the existing agent and installing a new one can solve an unknown issue.

There are some common errors that can be fixed without assistance from the Celigo Support team.

Failed to uninstall old application files. Please try running the installer again.: 2

Issue: You may encounter the following pop-up error dialog when using the Celigo agent, particularly after an automatic update.

Error: Failed to uninstall old application files. Please try running the installer again.: 2

Root cause: This issue is typically triggered when the Windows system PATH environment variable is in a corrupted or inconsistent state following the agent's auto-update process.

Solution: Restart the system. A full Windows restart often resolves the issue, as the operating system will attempt to automatically repair or reload critical environment variables (such as the PATH variable) during startup.

level=error, logName=heartbeatFailed, err=Error: connect ETIMEDOUT 72.44.45.92:443
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1300:16) {
  errno: -4039,
  code: 'ETIMEDOUT',
  syscall: 'connect',
  address: '72.44.45.92',
  port: 443
}
level=error, logName=requestTunnel, requesting tunnel failed 
error={"errno":-3008,"code":"ENOTFOUND","syscall":"getaddrinfo","hostname":"api.integrator.io"}

Agent group errors and solutions

An agent group lets a connection use up to three on-premise agents, so the connection keeps running when one agent goes offline. These are the issues you can meet when you use agent groups. For how agent groups work, see On-premise agent overview.

No healthy agents are available in an agent group

Symptom — Flow runs or the connection test fail with this error: No healthy agents are available in agent group {name}. Check agent status or add another member.

Cause — No agent in the group is available. Every agent is offline, has gone 60 seconds without a heartbeat, or failed with a connection error. A group with one agent shows this error whenever that agent is offline.

Resolution

1. Go to Resources, and then select On-premise agents.
2. In the agents table, find the agents whose Group column shows the group, and check each one's Status. The agents list can take up to 5 minutes to show an agent as offline, so an agent can appear online while runs fail.
3. Bring at least one agent back online. For each offline agent, follow Offline (red) status in integrator.io.
4. Retry the failed flow runs.

To keep this from recurring, add a second agent on a separate machine. See Set up an agent group.

Agent group doesn't exist or has been deleted

Symptom — Flow runs or the connection test fail with this error: Agent group {id} does not exist or has been deleted.

Cause — The connection still points to an agent group that was deleted.

Resolution — Open the connection and select a different agent group or a single agent. See Set up an agent group. If the group was deleted by mistake, restore it from the recycle bin.

Can't delete an agent group or an agent

Symptom — integrator.io won't delete an agent group or an agent and shows one of these messages:

• This agent group is used by one or more connections and cannot be deleted.
• This agent is a member of an agent group and cannot be deleted. Remove it from the group first.

Cause — A connection still uses the group, or the agent still belongs to a group.

Resolution

• To delete a group — Change every connection that uses the group to a different group or a single agent, and then delete the group.
• To delete an agent — Remove the agent from every group it belongs to, and then delete the agent.

For the steps, see Set up an agent group.

Can't add an agent to an agent group

Symptom — integrator.io won't save an agent group after you add an agent.

Cause and resolution

• The group already has three agents — A group can have up to three agents. Remove an agent before you add another.
• The agent is already in the group — Each agent can appear in a group only once.
• The agent belongs to a different environment — Every agent in a group must belong to the group's environment. Install and register an agent in this environment instead.
• The agent version is too old — An agent must be on version 6.0 or later to join a group. Update the agent, and then add it again. See Update your on-premise agent.

Agent shows as online but doesn't receive work

Symptom — The agents list shows an agent in a group as online, but flow runs go to another agent in the group.

Cause — This is expected in these cases:

• An agent earlier in the group's list is available. The first available agent in the list handles all of the group's work, and work isn't spread across agents.
• integrator.io stopped sending the agent new work, but the agents list hasn't caught up yet. It can take up to 5 minutes. For when integrator.io skips an agent, see How failover works.

Resolution — Check the agent's last heartbeat on the agents list. If the agent stopped sending heartbeats, see On-premise agent heartbeat failure. To change which agent handles work first, see Set up an agent group.

Duplicate records after a failover

Symptom — A destination app has duplicate records that were created around the time an agent in a group went offline.

Cause — When an agent stops partway through an import, the next agent can send some records from that import a second time.

Resolution — Remove or merge the duplicate records in the destination app. To prevent duplicates, design imports to update a matching record instead of always creating a new one.

In some cases, you'll need to use the agent logs to search for uncaught exceptions or other errors. An uncaught exception is an error that occurs during program execution but is not handled by any try/catch or equivalent exception-handling mechanism in the code. As a result, the program typically terminates abnormally, and a stack trace is often printed or logged to indicate where the error occurred. Uncaught exceptions can occur due to:

• File descriptor or memory limits
• Out of Memory (OOM): A condition where a system runs out of memory resources, leading to failures in executing processes. This situation often results in the operating system terminating processes to reclaim memory, which can cause unexpected crashes or degraded performance in applications. OOM conditions are typically associated with memory leaks or unbounded resource retention, which can impact system stability.
• Missing environment variables

Sometimes the error isn't found in the agent's logs. In those cases, you'll need to analyze your system-level logs.

You can create a support ticket at any time. Create one especially if you run into any of the following:

• An uncaught exception isn't self-explanatory.
• The agent crashes immediately after start.
• The issue is reproducible but not logged clearly.

Before you contact Celigo Support, gather:

• Agent log files
• If there is an uncaught exception, retrieve the uncaughtException file.
• Agent version
• OS details
• Flow or connection details that trigger the error