> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engini.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting the On Prem Agent

This guide helps you find out why a workflow step or tool call that uses your [On Prem Agent](/help/connections/on-prem-agent) failed, got stuck, or never ran. Most problems can be solved from the agent's own files on the machine where it is installed, without contacting Engini.

You will need access to the Windows machine that runs the agent (or someone from your IT team who has it).

## How the agent works

The agent runs as a Windows service named *Engini Agent*. It regularly asks Engini for new tasks, runs each one against your internal system (database, file system, HTTP API, and so on), and sends the result back to Engini. The connection is always outgoing from your network to Engini over HTTPS.

Every task has a numeric ID. The same ID appears in Engini, in the name of the task's file on the agent machine, and on every related line in the agent's log. This ID is how you connect what you see in Engini to what happened on the machine.

## Quick diagnosis

| What you see | Where to go |
| - | - |
| A step or tool call failed and shows an error | [Step 1](#step-1-read-the-error-in-engini), then [Step 2](#step-2-look-up-the-error) |
| The error is not in the Step 2 table, or you need to see exactly what was sent | [Step 4](#step-4-find-the-task-file) and [Step 5](#step-5-read-the-agent-log) |
| The agent shows *Offline*, or nothing runs | [Common problems](#common-problems) |
| A step waits a long time or never starts | [A step waits and nothing happens](#a-step-waits-and-nothing-happens) |

## Step 1 - Read the error in Engini

1. Open the workflow's [run history](/help/workflows/workflow-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](#step-2-look-up-the-error)).
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](/help/connections/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*.

The agent does not retry a failed task by itself. After you fix the cause, run the workflow or tool call again.

## Step 2 - Look up the error

When a task fails, Engini shows the error as `<what failed>. Details: <error>`. The part after `Details:` comes from your own system (database, API or file system), so read that part first. The same text appears in the `error=` part of the task's log line.

These are the errors we see most often, starting with the most widespread:

| The error contains | What it means | What to do |
| - | - | - |
| `Response status code does not indicate success: 400 (Bad Request)` | The HTTP endpoint rejected the request and sent no explanation. When an endpoint does explain, the agent shows its reply as the error instead of this text. | Check the URL, the parameters and the body the step sends. The task file shows exactly what was sent ([Step 4](#step-4-find-the-task-file)). |
| `Response status code does not indicate success: 401 (Unauthorized)` | The HTTP endpoint rejected the credentials. | Update the credentials in the connection. |
| `InterfaceErrors` | Priority rejected the document. The reason is written inside `InterfaceErrors`. | The error is long. Search it for `InterfaceErrors` and read the `text` value right after it, for example `"InterfaceErrors":{"@XmlFormat":"0","text":"שורה 1- ..."}`. That is Priority's message (`שורה 1` is line 1 of the document). Fix the data the step sends. |
| `<!DOCTYPE html` | The endpoint returned a web page instead of data. Usually the URL is wrong, or a proxy or login page answered instead of the API. | Open the URL from the agent machine and check what it returns. |
| `Duplicate key value specified`, `A record with the specified key` | A record with the same key already exists. | Update the existing record instead, or check whether it exists before you create it. |
| `Some queries are failed. Details: Failed queries: 1, 2, 3` | A *Create bulk of records* or *Update bulk of records* step ran, and your database rejected some of the records. The numbers are the positions of the failed records in the batch (`1` is the first record). | Look at the values of those records. In the task file ([Step 4](#step-4-find-the-task-file)) they are the `Queries` list, in the same order: `3` is the third `CommandText`. To see your database's exact error, run one of them as a single create or update. |
| `Connection login timed out`, `Communication link failure`, `No connection could be made because the target machine actively refused it` | The agent machine could not reach your server, or the server is not accepting connections on that address and port. | Check that the server is running, and check the host name, port and firewall from the agent machine. |
| `Value for column or variable ... too long` (DB2 `SQL0404`) | A value is longer than the database column allows. The column's name is in the error. | Shorten the value in the workflow before the step, or ask your database admin to widen the column. |
| `Incorrect syntax near`, `Unclosed quotation mark after the character string` | A value inserted into a custom SQL script contains an apostrophe (`'`), which breaks the script. Names and abbreviations often contain one, including Hebrew abbreviations. The text after `near` is what comes right after the apostrophe. | Find the value in the task file ([Step 4](#step-4-find-the-task-file)). In the script, replace each `'` in the inserted value with `''` (two apostrophes). |
| `was deadlocked on lock resources` | Your database stopped the query because another process was locking the same rows. | Run the workflow again. If it keeps happening, run the steps at a different time from other jobs on the same tables. |
| `Could not find a part of the path`, `The file at path ... was not found` | The folder or file does not exist on the agent machine. | Check the path from the agent machine. A drive that is mapped only for your Windows user is not visible to the *Engini Agent* service, so use the full network path (`\\server\share\...`) instead. |

If your error is not in this table, the text after `Details:` is still the message from your own system. Search it together with your system's name (for example *SQL Server* or *DB2*), or ask your system's admin. To see exactly what the agent sent, continue with the agent's files below.

## Step 3 - Find the agent's files

By default the agent is installed in:

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

If you chose another folder during installation, open *Services*, find *Engini Agent*, and check the path of its executable.

Two folders inside the install folder matter:

| Folder | What it tells you |
| - | - |
| `logs\` | What happened - the agent's running log, including errors. |
| `Tasks\` | What the agent was asked to do - one JSON file per task, sorted into a subfolder by stage. |

For most problems you need both: the task file shows the request, and the log shows what went wrong.

## Step 4 - Find the task file

Inside `Tasks\` there are six folders. A task file moves between them as the task progresses.

| Folder | What is in it | Look here when |
| - | - | - |
| `Pending\` | Tasks received from Engini that have not started yet. | Tasks pile up here: the agent is busy or not processing. Consider lowering the load or raising *Parallel Tasks Amount*. |
| `Processing\` | Tasks that are running right now. | A task seems stuck. |
| `Finished\<yyyy-MM-dd>\` | Tasks that succeeded, in a folder for the day they ran (UTC date). | You want to see exactly what a successful task did. |
| `ErrorResult\` | Tasks that failed. | A task failed and you want to see the request that was sent. This is the most useful folder. |
| `CloudTaskResult\` | Results waiting to be sent back to Engini. | This should be nearly empty. If it keeps growing, the agent cannot deliver results to Engini. |
| `OldUnsentCloudTaskResults\` | Results that could not be delivered to Engini for a long time. | The agent had a long connection problem with Engini. |

Old files are cleaned up automatically. By default, failed tasks are kept 30 days and finished tasks 60 days. Both periods are set in the agent's settings (*Error Folder Retention Days* and *Finished Folder Retention Days*).

To find your task's 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.

File names follow this pattern:

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

*Priority* is `Standard` for workflow steps and tool calls. `High` is used for internal tasks, such as updating the agent's settings or loading a database's tables and fields while you build a step. For example: `Standard_4823917_Database_RetrieveRecords.json`. Some tasks have no operation type, so that last part may be missing.

The file contains the request the agent received:

* **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

The log files are in the `logs\` folder. Two kinds of file are written, and a new file starts every day:

| File name | Contains |
| - | - |
| `general<yyyyMMdd>.log` | Everything the agent logs - startup, tasks picked up, tasks started and finished, warnings and errors. |
| `exceptions<yyyyMMdd>.log` | Only the errors. It is much smaller. |

For example, the log for 15 October 2026 is `general20261015.log`. Each file is limited to 10 MB (if it fills up, the agent starts another file for the same day), and the agent keeps the most recent 31 files of each kind.

> **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.

To search a log:

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.

On each line about your task, the part after `error=` is the message from your system - the same text Engini shows on the failed step.

A failed task looks like this in the log (the parts are separated by tabs):

```
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.'
```

The parts are the time, the level (`[INF]`, `[WRN]`, `[ERR]`, or `[DBG]` with the debug level), the task ID, and the message. `type` tells you what kind of task it was, for example `MsSqlServerTask`, `HttpCloudTask` or `PrioritySdkCloudTask`.

The messages you will meet most often:

| Message starts with | Meaning |
| - | - |
| `Cloud task started` | The agent began running the task. |
| `Cloud task successfully completed` | The task worked. If the workflow still fails, the problem is in a later step. |
| `Cloud task failed` | The task ran but your system returned an error. Read the `error=` part. |
| `Failed to process cloud task` | The agent hit an unexpected error while running the task. This one also appears in the exceptions log. |
| `Failed to send result for cloud task` | The task ran, but the agent could not deliver the result to Engini. Check the agent machine's internet access. |

## PowerShell commands

You can run these on the agent machine instead of browsing folders. The service shown as *Engini Agent* in *Services* is named `EnginiAgent` in PowerShell. Set `$id` to your task ID. Starting or stopping the service needs an administrator PowerShell.

For a failed task, run them in this order: check the service, search the log for the task ID, find the task file (its folder is the task's stage), then look up the `error=` text in [Step 2](#step-2-look-up-the-error). When you report back, include the `error=` text, the stage folder and the task `type`, with passwords and tokens replaced by `REDACTED`.

```powershell theme={null}
# 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
```

How to read the results:

| Log search | File search | Meaning |
| - | - | - |
| `Cloud task failed` line | File in `ErrorResult\` | The task failed. The `error=` part says why - look it up in [Step 2](#step-2-look-up-the-error). |
| `Cloud task successfully completed` line | File in `Finished\<date>\` | The task worked. If the workflow still fails, the problem is in a later step. |
| `Cloud task started`, but no completed or failed line | File in `Processing\` | The task is still running, or stuck. See [A step waits and nothing happens](#a-step-waits-and-nothing-happens). |
| Only `Cloud task added to Pending stage` | File in `Pending\` | The task is waiting its turn. The agent is busy with other tasks. |

If neither the log search nor the file search finds the task ID, the task never reached this agent (check the agent's status in Engini, and that the step uses this agent), or it is older than the logs and files the agent keeps.

> **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

Check these in order:

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

| Symptom | What to check | Usual fix |
| - | - | - |
| The agent shows *Offline* and nothing runs. | Is *Engini Agent* running in *Services*? | Start or restart the service. If the machine was restarted, check that the service started with it (its *Startup type* in *Services* should be *Automatic*). If it still shows Offline, allow outgoing HTTPS from the agent machine to `opa.engini.io` (test it with `Test-NetConnection opa.engini.io -Port 443` - `TcpTestSucceeded : True` means it is reachable), and look at the end of the newest `general<date>.log`. If the log shows `Application is going to be stopped because of the status code='Unauthorized'` (or `'NotFound'`), Engini rejected the agent's token and the agent stopped itself. Restarting will not help - send the log to Engini support. |
| Steps wait for a long time, and files accumulate in `Tasks\Pending\`. | Is the agent online? How many tasks run at once? | Raise *Parallel Tasks Amount* (the default is 2), if the machine can handle it: **Connections** > **On-Prem Agents** > the agent's actions menu > *Edit*. |
| A step runs longer than expected, and the file stays in `Tasks\Processing\`. | Search the log for the task ID. *Task Timeout* (default 300 seconds) limits each database query and file operation, and *Http Timeout* (default 300 seconds) limits each HTTP call. | If the file is still there long after that, restart the service (read the warning [above](#a-step-waits-and-nothing-happens) first) and send the logs to Engini support. |
| `Tasks\CloudTaskResult\` keeps growing. | The agent cannot send results to Engini. | Allow outgoing HTTPS from the agent machine to `opa.engini.io`. |
| The log shows `Failed to deserialize cloud task from file`. | The agent received a task it does not understand. | Send the logs to Engini support. The agent may need an update. |

## Get more detail with the debug log level

By default the agent logs at the *Information* level. If the usual log does not explain a problem, you can switch to *Debug* for a short time:

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.

Do not leave *Debug* on. It writes much more to disk and the 10 MB daily files fill up faster, so older history is deleted sooner.

## Download the logs

Open the actions menu on the agent's row in **On-Prem Agents** and choose *Download logs*. This works only while the agent is not *Offline*. The agent packs the files in its `logs\` folder into one zip file (up to 50 MB; the newest files are included first). This does not include the `Tasks\` folder.

If the agent is *Offline*, or you also need the task files, zip the `logs\` folder and the relevant `Tasks\` subfolders on the agent machine yourself.

## What to send Engini support

If you could not solve the problem, send us the following in one message. It saves us a round of questions:

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?

You can reach us at [info@engini.io](mailto:info@engini.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.