Troubleshooting the On Prem Agent

​

How the agent works

​

Quick diagnosis

​

Step 1 - Read the error in Engini

1. Open the workflow’s run history and open the failed run. A tool call also creates a run in the history, so look it up the same way.
2. Open the failed step and read the error message. Often this already tells you the cause (see Step 2).
3. Copy the OPA Task ID shown in the step details. You will use it to find the task on the agent machine.
4. Open Connections and then On-Prem Agents, and check the agent’s status:
   • Online - the agent is running and talking to Engini.
   • Waiting for connection - a new agent that has not connected to Engini yet. Install the agent and start the service (see On Prem Agent).
   • Offline - Engini has not heard from the agent recently. Open Services on the agent machine, check that Engini Agent is running, and start or restart it.
   • Disabled - the agent was disabled. Open the actions menu on the agent’s row and choose Enable.

​

Step 2 - Look up the error

​

Step 3 - Find the agent’s files

C:\Program Files\Engini On-premise Agent\

​

Step 4 - Find the task file

1. Open File Explorer and go to the folder that matches the task’s situation (for a failed step, start with ErrorResult\).
2. Paste the task ID into the search box at the top right of the window. The file name contains the ID.
3. Open the file with Notepad, or any text editor.

<Priority>_<TaskId>_<TaskType>_<OperationType>.json

• HTTP steps - the URL (Url), the method (Method), the headers (Headers) and the body (BodyContent).
• Custom SQL scripts - the exact script the agent ran, with your values already inserted. This is where you find a value that breaks the script.
• Other steps - the connection details and the query or file path the agent used.

Important: task files can contain credentials, for example inside a connection string. Before you send a task file to anyone, replace every password, key and token in it with REDACTED.

​

Step 5 - Read the agent log

Tip: a task that fails because of its own request, such as wrong credentials, an unreachable server or a timeout, is recorded as a warning in general<date>.log. It is not in exceptions<date>.log. The exceptions file only collects errors, such as the agent failing to process or deliver a task. Search general<date>.log first, and use exceptions<date>.log when the agent itself seems to misbehave.

1. Open the file for the day of the failure in Notepad.
2. Press Ctrl+F and paste the task ID.
3. Click Find Next to read all the lines about that task. Typically you will see when the task was picked up, when it started, and how it ended.

2026-10-15 09:12:44.031  [WRN]  CloudTaskId:4823917  Cloud task failed. CloudTaskId='4823917', type='MsSqlServerTask', result='Failure', error='Failed to execute operation. Details: Transaction (Process ID 265) was deadlocked on lock resources with another process and has been chosen as the deadlock victim. Rerun the transaction.'

​

PowerShell commands

# The agent's install folder, found from the service
$opa = Split-Path (Get-CimInstance Win32_Service -Filter "Name='EnginiAgent'").PathName.Trim('"') -Parent
$id  = "4823917"   # your task ID

# Is the agent service running?
Get-Service EnginiAgent

# Can the agent machine reach Engini over HTTPS? (look for TcpTestSucceeded : True)
Test-NetConnection opa.engini.io -Port 443

# Restart the agent service (administrator) - it re-runs every task in Tasks\Processing, see "Before you restart" below
Restart-Service EnginiAgent

# Every log line about one task, oldest first: started, then completed or failed (searches all daily log files)
Select-String -Path "$opa\logs\general*.log" -Pattern $id

# Only the failure lines for that task
Select-String -Path "$opa\logs\general*.log" -Pattern $id | Where-Object { $_.Line -match "failed|error=" }

# The task's file - the folder in the path is its stage: Pending, Processing, ErrorResult or Finished
Get-ChildItem "$opa\Tasks" -Recurse -Filter "*_${id}_*" | Select-Object FullName, LastWriteTime

# Show the task file's contents (it can contain passwords - redact before sharing)
Get-ChildItem "$opa\Tasks" -Recurse -Filter "*_${id}_*" | Get-Content

# Errors of the agent itself, newest log
Get-ChildItem "$opa\logs\exceptions*.log" | Sort-Object LastWriteTime | Select-Object -Last 1 | Get-Content -Tail 50

# How many tasks are waiting
(Get-ChildItem "$opa\Tasks\Pending" -Filter *.json).Count

# The last 50 lines of the newest log
Get-ChildItem "$opa\logs\general*.log" | Sort-Object LastWriteTime | Select-Object -Last 1 | Get-Content -Tail 50

Before you share output: task files and log lines can contain passwords and tokens. Replace them with REDACTED before you paste the output anywhere, including into an AI assistant.

​

Common problems

​

A step waits and nothing happens

1. The agent’s status in Engini (Connections > On-Prem Agents). If it is Offline, the agent cannot pick up tasks. See the first row of the table below.
2. Files in Tasks\Pending\ - the agent received the tasks but is busy with others. Raise Parallel Tasks Amount (second row below).
3. The task’s file in Tasks\Processing\ for much longer than the timeouts - the task is stuck. Task Timeout (default 300 seconds) limits each database query and file operation, and Http Timeout (default 300 seconds) limits each HTTP call. Read the warning below, then restart the service and send the logs to Engini support.

Before you restart: when the service starts, every task in Tasks\Processing\ goes back to Pending\ and runs again from the start. If the stuck task writes data (for example an insert, an update or an HTTP POST), check first whether it already did, so it is not written twice.

​

Other problems

​

Get more detail with the debug log level

1. Open Connections and then On-Prem Agents.
2. Open the actions menu of the agent and choose Edit.
3. Set Log Level to DEBUG and click Save. The agent switches to the new level right away, without a restart. This works only while the agent is not Offline. The agent does not store the log level on its machine. If the Engini Agent service restarts, it goes back to INFORMATION, even though Engini still shows DEBUG. To turn debug on again, open Edit and click Save.
4. Run the workflow again, then look at general<date>.log.
5. When you are done, set Log Level back to INFORMATION and save.

​

Download the logs

​

What to send Engini support

1. Your account and workspace name.
2. The agent’s name.
3. The workflow name and the link to the failed run.
4. The error message shown on the failed step.
5. When it started failing, including your time zone.
6. What you already tried (for example restarted the service, checked the credentials).
7. The logs zip, and the task file from Tasks\ErrorResult\ for the failed task, with all passwords and tokens replaced by REDACTED.
8. The scope: is it one task, one workflow, or every task on this agent?