On-premise agents: Troubleshooting and FAQs

Delete the existing OPA and install a new one:

Delete the existing OPA and install a new one:

There are generally three reasons why the OPA is offline in integrator.io. Before contacting Celigo Support, check the following:

If these are all working as expected, check your logs for any of the common errors and solutions listed below. If none of the errors appear, contact Celigo Support.

Issue: In some cases, the OPA won't automatically upgrade when a new version is released.

Root cause and Solution: This occurs if the OPA isn't running as a service or if you're missing administrator privileges (Windows only).

Issue: Can't find logs or the log files are empty.

Root cause: You may have an OPA running with incorrect permissions, or a misconfigured or inaccessible log path.

Troubleshooting: Determine if the log files exist.

Windows:

Linux:

Logs are created in the /root/.config/agent/ folder of your Linux machine.

Issue: You may encounter the following pop-up error dialog when using the Celigo OPA, 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 OPA'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.

Symptom: The Celigo on-prem agent service is not running in the Services application.

Root Cause / Additional Information: The on-prem agent can be executed in three modes:

If the service fails to start or stops unexpectedly, determine if the OPA is running in Background mode or via the UI. Ensure that the OPA is not running and terminate running instances before restarting the service.

In some cases, the OPA's heartbeat could fail during normal operations. Heartbeats are sent periodically (approximately every 60 seconds). Long gaps between heartbeat logs could indicate the OPA stopped or lost connectivity. There are several potential causes for failed heartbeats:

To determine if your OPA is functioning properly, check your logs (Windows, Linux). Use a text editor or command-line tool (grep, findstr) to find success or error logs.

A successful heartbeat can appear with any of the following success log messages:

A failed heartbeat can appear with any of the following error log messages:

If you find any of the above errors, check the logs again to determine if the OPA was able to connect to a tunnel. Successful tunnel messages usually look as follows:

If your log isn't able to connect to a tunnel, it could mean that the server was not able to establish a connection to the Internet. Check for the following entries in the logs:

If noInternet appears, inspect nearby log entries for: heartbeatFailed. If both noInternet and heartbeatFailed are logged around the same time, it strongly suggests a network connectivity issue on your machine or server. There are generally two causes for network connectivity issues:

Sample logs:

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"}

You can expect to see this log error approximately three times before the OPA connects to the tunnel, since sometimes the OPA tries to switch ports to find a free one. It may be an issue with Celigo's infrastructure if it's happening often and and in continuous intervals, leading to the OPA appearing Offline (red) in integrator.io. There are several other potential causes:

To determine if your OPA is functioning properly, check your logs (Windows, Linux). Use a text editor or command-line tool (grep, findstr) to find the following log:

2025-05-01T22:59:50.176Z: level=error, logName=forwardInError, code=undefined, message=Unable to bind to 0.0.0.0:7017, stack=Error: 

If you see the logged error, contact Celigo Support.

If you are using on-prem JDBC connections, make sure JDK 17 is installed.

For Oracle database on-premise connections, the Oracle instant client must be installed on the user's computer.

To find your OPA's logs and analyze uncaught exceptions:

To check for system-level triggers, use the Windows Event Viewer to search for:

You can also use PowerShell commands like: Get-EventLog -LogName System

Logs are created in the /root/.config/agent/ folder. To find your OPA's logs and analyze uncaught exceptions:

To check for system-level triggers, execute any of the following commands: /var/log/syslog, /var/log/messages, dmesg.

After uninstalling the OPA service, you may get an uncaught exception error and your OPA may crash. The error will include Error: EPERM: operation not permitted, unlink.

To uninstall the OPA service properly after receiving this error, click Uninstall service again in the OPA UI.