On-prem setup & installation issues

This guide covers common issues that occur when you install or initialize the on-prem agent (OPA). These errors result from permission problems, invalid configuration files, or environment-level restrictions.

Issues with the connection details in the config.yml file

The config.yml file in <INSTALL_HOME>/conf/config.yml defines how the agent connects to Workato. Incorrect authentication entries in the YAML file can cause the agent to fail at startup. Ensure your authentication details are accurate.

Issues with config.yml file formatting

The config.yml file requires strict indentation and spacing. A misplaced space or newline causes YAML parsing failures. Use an online validator to check the format before you start the agent and remove sensitive information before you use any external tools.

Issues with the account used to run the OPA

The agent may fail to start if the assigned service account lacks required permissions. Assign a user with higher privileges to resolve the issue. For example, in Windows:

1

Press Win + R, type services.msc, and press Enter.

2

Go to the Services window and locate the agent.

3

Right-click on the OPA agent and select Properties.

4

Switch to the Log on tab.

5

Change the account used to run the agent to one with higher privileges.

Change your account

The agent lost access to the logs folder

Cleanup jobs or automated server processes may delete the logs folder. The agent can't launch without access to this folder.

OPA error

Recreate the logs folder to restore access. Note that certain server applications or rules may repeatedly delete the OPA logs folder. Reinstall the OPA using an account with higher privileges if this issue continues.

Error: Unable to create directory [work] to use as the base directory

The agent may fail at startup with an Unable to create directory [work] to use as the base directory error when it lacks permission to create the work directory. This issue often occurs when the agent runs under a limited-privilege account.

Initialization error

Run the agent with an administrator account to avoid this error. If the agent runs as a service, confirm that the assigned service user has full access to the install path.

PKIX path building failed error

You may see the following error in logs when the agent starts:

javax.net.ssl.SSLHandshakeException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

This error typically occurs when a proxy or firewall intercepts the connection between the OPA host and Workato's gateway.

Complete the following steps to resolve the issue:

1

Confirm whether your environment uses an outbound proxy or SSL inspection layer.

2

Configure your proxy settings in the config.yml file under the proxy: section. Refer to the Set up proxy access for your on-prem agent section for more information about defining proxy settings.

3

Ensure the proxy allows HTTPS connections to Workato endpoints.

Review logs for startup failures

Check the OPA logs when the agent doesn't start or connect. Repeated "agent connected" and "disconnected" entries often indicate unstable network connectivity. You can monitor agents version 2.14.0 and newer to gather additional information regarding agent performance.

SSL errors like PKIX path building failed or full exceptions such as com.workato.agent.net.AgentNonRecoverableException: Error connecting to the gateway sg3.workato.com:443 javax.net.ssl.SSLHandshakeException: PKIX path building failed usually indicate that a proxy or firewall blocks the agent's connection to Workato's gateway.

These patterns can help confirm whether the issue comes from configuration, permissions, or network restrictions.

Installation best practices

Apply the following practices to ensure the agent starts reliably and runs without interruption.

Confirm access to Workato's gateway

Ensure the machine running the OPA agent can reach sg3.workato.com and sg4.workato.com over port 443. Firewalls or proxies that block outbound HTTPS traffic can prevent the agent from connecting.

Use consistent configuration management

Validate the config.yml file in a test environment before production deployment. Store validated versions of the file for rollback and configuration tracking.

Isolate agent instances

Install each agent in a separate path with its own configuration and certificate set. Don't share folders or service accounts across agents.

Optimize data efficiency

Deploy the agent in the Workato data center nearest to the on-prem system. This setup reduces latency and supports large-volume or high-throughput data.

Handle credentials securely

Use a secrets manager to store credentials. Don't embed credentials directly in the YAML file or store them in plaintext. For setups that rely on a legacy YAML configuration, protect the file and restrict access.

Windows installation

Use Local Service as the default account for the OPA service. This account provides restricted access. Most teams configure a domain-specific service account to manage permissions and ensure proper access to required resources.

Linux installation

Use a package manager to install OPA. Configure it as a service to enable automatic restarts after server reboots.