On-prem agent (OPA) error troubleshooting

Use this guide to troubleshoot common issues with the Workato on-prem agent (OPA). These guides cover setup, upgrades, runtime behavior, and extensions.

REVIEW LOGS

Refer to the following sections to locate and investigate errors in OPA logs:

• OPA log generation and retention: Learn where to find logs and how to interpret them.
• Job-level troubleshooting: Use job IDs to trace failures in logs.

Choose a guide based on the issue you plan to troubleshoot:

• Setup and installation issues: Covers agent startup failures, permission errors, directory creation problems, and proxy-related SSL errors.
• Upgrade and configuration issues: Fixes post-upgrade failures, service account resets, and connection profile changes.
• Runtime and performance issues: Resolves heap memory crashes and large response buffering problems.
• Kafka - No profile found error: Fixes configuration mismatches that prevent the agent from recognizing Kafka profiles.
• 520 Java extension error: Explains how to fix the 520 Connection Failed error during SDK extension startup.

OPA log generation and retention

You can use OPA logs to identify agent behavior and system issues during execution. The OPA generates a new log file daily based on the on-premise system time. If a log file exceeds 20 MB within a day, a new one is created and numbered sequentially. For example, if /agent-2019-11-01.0.log is the first log of the day, additional logs for the same day are /agent-2019-11-01.1.log and /agent-2019-11-01.2.log. The OPA retains the latest 60 log files or a maximum of 20 GB of logs.

Locate OPA logs

You must locate the log files to troubleshoot OPA issues. Depending on your operating system, complete the following instructions for Windows or Linux:

Windows

Log files are stored in %SYSTEMROOT%\System32\LogFiles\Workato by default for on-prem agents operating as a Windows service. You can navigate to this file manually or use the shortcut in the Start menu under All apps > Workato.

Complete the following steps to change the log storage location:

1

Open the Windows Start menu.

2

Go to All apps > Workato.

3

Click Service Wrapper Configuration to open the configuration menu.

4

Go to the Logging tab.

5

Enter a new log storage location in the Log path field.

6

Click Apply, then OK.

OPA LOG CONTENTS

The level of detail included in your OPA logs depends on your agent configuration. Refer to the Workato logging levels section for more information.

Linux

Log files are stored in /var/log/messages by default for on-prem agents operating as a Linux service through systemd. Because this file also contains logs from other Linux services, you must use the journalctl command to access OPA specific logs.

journalctl -u [name of the OPA service].service

The -u switch filters the logs returned by the service that created them. Replace [name of the OPA service] with the name you set for the OPA during installation.

You can further refine your log search using the following commands:

• > [output-file]: Exports the result of journalctl to a file.
• --since: Limits the generated logs to after a specific date and time.
• --until: Limits the generated logs to before a specific date and time.

For example:

journalctl -u workato.service --since "2020-07-26 23:15:00" --until "2020-08-5 23:20:00" > OPALogs.txt

Refer to Loggly's Using journalctl (opens new window) guide for additional journalctl information.

OPA LOG CONTENTS

The level of detail included in your OPA logs depends on your agent configuration. Refer to the Workato logging levels section for more information.

Job-specific troubleshooting

Use the job ID to search OPA logs and trace job execution across all stages. This allows you to isolate OPA-specific operations within a single job. For example: j-AHd9XdsW-JppW.

Locate jobs