On-prem upgrade & configuration issues

This guide explains common issues you may encounter when you upgrade the on-prem agent (OPA) or reconfigure its settings. These problems often result from changes to service behavior, configuration paths, or connection logic across OPA versions.

Back up config.yml before the upgrade

Create a copy of your current config.yml file before you start the upgrade. This ensures you can restore your authentication and connection settings if the upgrade overwrites the configuration. If your file includes encrypted passwords, you must re-encrypt them after the upgrade. Encrypted values are tied to the agent's private key and don't transfer between agents.

Activate firewall ports

Open outbound TCP port 443 to sg3.workato.com and sg4.workato.com before you upgrade from OPA version 2.10.0 or earlier.

Restore the original service account if the upgrade resets it

Upgrades may reset the OPA service to use a local account instead of the previously configured user account. This change can disrupt existing connections, such as SQL server connections with integrated security=true or file connections to shared drives.

Connection error

You can change the Windows service configuration back to the previously configured user account to resolve the issue.

Use separate keys for each agent

Assign a unique set of key files to each agent on the same server. Sharing files like cert, key, or cert.pem can cause authentication failures.

Reconnect HA agents after the upgrade

Re-establish configuration between upgraded agents in high-availability (HA) setups. Copy the config.yml file to each new or restored agent, and confirm the service account can access all mounted paths. If the file contains encrypted passwords, you must re-encrypt them for each agent. Encrypted values rely on agent-specific keys and don't work across different agents.

Connection profiles with new versions

Create a new on-prem group when you use OPA version 2.15.0 or higher and avoid assigning cloud connection profiles to the same group used by older agents. You can use the Directly in Workato option to create the group, then add a new agent to manage those profiles.

Set up connections