> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/troubleshooting-the-abap-agent.md).

# Troubleshooting the ABAP Agent

{% hint style="info" %}
**Start here:** Run `slabapcli setup status` to check all common prerequisites in one command. It verifies SeaLights connectivity, RFC connections, SAP authorizations, SCMON state, and agent-side prerequisites. See [Validate Your Setup](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/validate-your-setup.md).
{% endhint %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before troubleshooting, confirm the following are in place:

* **Windows**: Windows 10 version 1903+ or Windows Server 2022+
* **SAP**: NetWeaver 7.4.8+ with SCMON capability (if you can't download it, make sure your user has the needed permissions)
* **ABAP Addon**: Installed on the QAS system via SAINT transaction (provides `/TRICE/` namespace RFCs)
* **Network**: RFC access to SAP systems (port 33xx) and HTTPS access to SeaLights API endpoints
* **Agent Config**: Valid `config.toml` at `%ProgramData%\Tricentis\SeaLights\ABAP Agent\config\config.toml`, schema version 4, with correct RFC, pipeline, and SeaLights settings

***

### Agent Logs <a href="#agent-logs" id="agent-logs"></a>

Once the agent is onboarded, **server task logs** are the primary place to diagnose failures for Initial Build Map, Refresh Links, test-repository search/test, and other server-backed work. Watcher-local pipeline logs (Build Modifications, Footprints) and CLI console output are secondary.

Default userdata root: `%ProgramData%\Tricentis\SeaLights\ABAP Agent` (override with `[settings].userdata`). C++ components write under `public\Logs` (capital **L**); the .NET server and AdapterHost write under `public\logs` (lowercase). On Windows these resolve to the same folder.

Field reference and full inventory: [Configuration settings — Log locations](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#log-locations).

#### Server task logs (start here) <a href="#server-task-logs" id="server-task-logs"></a>

When a **server-backed** task fails, open the per-task folder under the server logs root first:

```
{userdata}\public\logs\{taskType}\{yyyy-MM-dd}\{processId}\
```

| Path piece     | Meaning                                                                    |
| -------------- | -------------------------------------------------------------------------- |
| `{taskType}`   | Server task kind (folder name matches the task type)                       |
| `{yyyy-MM-dd}` | UTC date when the task log directory was created                           |
| `{processId}`  | Server task-run ID (not the Windows PID) — each run gets its own subfolder |

Inside that folder:

| File                      | Contents                                                   | Config lever                    |
| ------------------------- | ---------------------------------------------------------- | ------------------------------- |
| `{processId}.log`         | Server-side orchestration for that task run                | `[server.logging].defaultLevel` |
| `agent.log`               | Native CAPI / `slabap.agent.dll` work for that task        | `[logging]` (native)            |
| `{processId}_adapter.log` | Adapter host / external tool calls (when AdapterHost runs) | `[adapters].logLevel`           |

**Where to look first when a server task fails**

1. Identify the `taskType` folder for the failing work (table below).
2. Open today’s (or the failure day’s) `{yyyy-MM-dd}` directory under that folder.
3. Pick the `{processId}` subfolder for the failed run — use the newest folder if you are unsure, or match the `processId` from watcher/CLI output or from `server-YYYYMMDD.log`.
4. Read `{processId}.log` and `agent.log` side by side. For test-repository work, also open `{processId}_adapter.log` (adapter auth, proxy, and tool API errors usually appear there).

**How to find `processId`:** check `public\logs\server-YYYYMMDD.log` for the task start, use the subdirectory name under `public\logs\{taskType}\{date}\`, or use the `processId` printed in watcher/CLI task output.

**Common `taskType` folders**

| Watcher / CLI action                                           | `taskType` folders under `public\logs\`                                                                                              |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `INIT_BUILD_MAP` (Initial Build Map)                           | `generate_cache` → `sync_phd` → `generate_common` → `generate_links` → `generate_graph` → `generate_buildmap` (one folder per stage) |
| `REFRESH_LINKS`                                                | `generate_cache`, `sync_phd`, `generate_links`, `generate_graph`                                                                     |
| `SEARCH_TESTREPO`                                              | `search_testrepo`                                                                                                                    |
| `slabapcli testrepo test` (and auto-test after `testrepo set`) | `test_testrepo`                                                                                                                      |
| `upload_flpca import`                                          | `upload_flpca`                                                                                                                       |

IBM stage roles: [Create an Initial Build Map for your Pipeline](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/create-an-initial-build-map-for-your-pipeline.md). Refresh Links: [Refresh links and impacted graph](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/refresh-links.md).

The server also writes a daily host log at `public\logs\server-YYYYMMDD.log` (startup, readiness, and task lifecycle). Use it to find `processId` or diagnose “server won’t start / returns 503”. Early interactive bootstrap (before userdata resolves) may also write under `{install}\logs\server\`.

#### Which log to open (symptom → log) <a href="#symptom-log-matrix" id="symptom-log-matrix"></a>

| Symptom                                             | Start here                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Initial build map fails, stalls, or restarts        | Server task folders for the failing stage under `public\logs\` (`generate_cache` → … → `generate_buildmap`) — that day’s `{processId}` → `{processId}.log` and `agent.log`. Optionally skim `public\Logs\{pipeline}\InitialBuildMapping_YYYY-MM-DD.log` for watcher orchestration context. |
| Links / impacted-graph refresh fails or looks stale | Server task folders `generate_cache`, `sync_phd`, `generate_links`, `generate_graph` under `public\logs\` for that day’s `{processId}`. Optionally skim `public\Logs\{pipeline}\RefreshLinks_YYYY-MM-DD.log`.                                                                              |
| `testrepo test` fails                               | `public\logs\test_testrepo\{date}\{processId}\{processId}.log` and `{processId}_adapter.log`                                                                                                                                                                                               |
| Test-repository search / recommended tests fail     | `public\logs\search_testrepo\{date}\{processId}\{processId}.log` and `{processId}_adapter.log`                                                                                                                                                                                             |
| Adapter auth, proxy, or tool API errors             | Prefer `{processId}_adapter.log` in the same task folder; raise `[adapters].logLevel` if needed                                                                                                                                                                                            |
| FLPCA upload import fails                           | `public\logs\upload_flpca\{date}\{processId}\{processId}.log` (and `agent.log` if present)                                                                                                                                                                                                 |
| Server won’t start or returns 503                   | `public\logs\server-YYYYMMDD.log` (and `{install}\logs\server\` if interactive host failed before userdata resolve)                                                                                                                                                                        |
| Build modifications fail                            | **Watcher-local only:** `public\Logs\{pipeline}\BuildMods_YYYY-MM-DD.log` (no server `taskType` folder for scheduled `BUILD_MODS`)                                                                                                                                                         |
| Footprints / coverage collection issues             | **Watcher-local only:** `public\Logs\{pipeline}\Footprints_YYYY-MM-DD.log`                                                                                                                                                                                                                 |
| CLI command unclear / no file log                   | Console only — redirect stdout/stderr                                                                                                                                                                                                                                                      |

#### Watcher-local and other logs (secondary) <a href="#watcher-local-and-other-logs" id="watcher-local-and-other-logs"></a>

These are **not** server per-task folders. Use them for watcher orchestration context, watcher-local pipelines, or maintenance — after checking server task logs for server-backed failures.

| Component                         | Default log location                                                                                                                                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pipeline watcher summaries        | `{userdata}\public\Logs\{pipeline}\InitialBuildMapping_YYYY-MM-DD.log`, `RefreshLinks_YYYY-MM-DD.log`, `BuildMods_YYYY-MM-DD.log`, `Footprints_YYYY-MM-DD.log` |
| Watcher bootstrap (`main_logger`) | `%ProgramData%\Tricentis\SeaLights\ABAP Agent\public\Logs\watcher\main_logger_<timestamp>_<pid>.log` (always under ProgramData, even if userdata is relocated) |
| Log purger (`purgeLogs.exe`)      | `{userdata}\public\Logs\purger_YYYY-MM-DD.log`                                                                                                                 |
| CLI (`slabapcli.exe`)             | Console only (stdout/stderr) — no log file                                                                                                                     |

{% hint style="info" %}
**The CLI does not write a log file.** Redirect output when you need to keep it: `slabapcli.exe setup status > status.txt 2>&1`. Server-backed work writes the per-task folders above; Build Modifications and Footprints write only the watcher-local pipeline daily logs.
{% endhint %}

#### Log Levels <a href="#log-levels" id="log-levels"></a>

C++ agent and watcher verbosity is configured in the `[logging]` section of `config.toml`:

```toml
[logging]
level = "info"           # File log level: trace, debug, info, warn, error, critical
consolelevel = "info"    # Console log level (CLI interactive output)
flushinterval = 5        # Seconds between flush to disk
flushlevel = "info"      # Minimum level that triggers immediate flush
retentionperiod = 14     # Days to keep log files
```

Server per-task logs (`{processId}.log`) use `[server.logging].defaultLevel`. Adapter host logs (`{processId}_adapter.log`) use `[adapters].logLevel`. Field reference: [Configuration settings](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#log-locations).

For troubleshooting, temporarily set `level = "debug"` or `level = "trace"` (and the matching server/adapter levels if needed) to capture detailed RFC calls, HTTP requests, and data processing steps. Restart any running scheduled tasks after changing the log level. Remember to restore `level = "info"` once the issue is resolved to avoid excessive log growth.

#### What to Look For <a href="#what-to-look-for" id="what-to-look-for"></a>

When a server-backed task fails, open that run’s `public\logs\{taskType}\{date}\{processId}\` folder and check:

* **`[error]`** lines in `{processId}.log` and `agent.log` — exception details and source references.
* **RFC errors** — connection, authorization, and data retrieval failures (see [SAP System Errors](#sap-system-errors) below).
* **HTTP errors** — SeaLights API communication failures, SSL issues, or token problems (see [SeaLights Connection Errors](#sealights-connection-errors) below).
* **Mismatched server vs adapter detail** — if `{processId}.log` looks fine but the external tool call failed, open `{processId}_adapter.log` (and the reverse if AdapterHost never started).
* **Repeated restarts** — the same stage/`processId` pattern failing again indicates a persistent configuration or authorization issue.

For watcher-local Build Modifications or Footprints, use the same checks in the pipeline daily log under `public\Logs\{pipeline}\`.

***

### Server Issues <a href="#server-issues" id="server-issues"></a>

The ABAP Agent server (`SLABAPServer.exe`) runs as a **foreground console process** bound to `http://127.0.0.1:17500`. See [Start the ABAP Agent Server](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/start-the-agent-server.md) for startup instructions.

#### Server won't start or exits immediately <a href="#server-wont-start" id="server-wont-start"></a>

**Symptoms:** `SLABAPServer.exe` exits before printing `APPLICATION STARTED`, or the console closes immediately.

**Diagnostic steps:**

1. Check the server log for the startup error:

   ```
   %ProgramData%\Tricentis\SeaLights\ABAP Agent\public\logs\server-YYYYMMDD.log
   ```

   For an interactive (non-service) host that failed early, also check `{install}\logs\server\server-YYYYMMDD.log`.
2. Run `slabapcli setup status` to verify `config.toml` has no syntax errors and all prerequisites are met.
3. Confirm the SeaLights token is set and valid: `slabapcli sealights test`.
4. Check whether port 17500 is already in use:

{% tabs %}
{% tab title="Command Prompt" %}

```batch
netstat -ano | findstr :17500
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Get-NetTCPConnection -LocalPort 17500 -ErrorAction SilentlyContinue
```

{% endtab %}
{% endtabs %}

If port 17500 is in use, stop the conflicting process or change the server port in `config.toml` (field `[server].port`). See [Configuration settings](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md).

#### Server not reachable or returns 503 <a href="#server-not-reachable" id="server-not-reachable"></a>

The server exposes a readiness probe at `GET http://127.0.0.1:17500/ready`. Check server readiness before running commands that depend on the server:

{% tabs %}
{% tab title="Command Prompt" %}

```batch
curl http://127.0.0.1:17500/ready
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Invoke-RestMethod http://127.0.0.1:17500/ready
```

{% endtab %}
{% endtabs %}

| HTTP response                                                                                     | Meaning                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` — `{"status":"ready"}`                                                                   | Config valid, SeaLights token validated, process database ready.                                                                                                                                                                                                                               |
| `503 Service Unavailable` — `{"status":"not_ready", "reasonCode":"CONFIG_RESTART_REQUIRED", ...}` | A cold configuration field changed since startup. Restart `SLABAPServer.exe` to apply it. See [Live reload and restart-required fields](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#live-reload-and-restart-required-fields). |
| `503 Service Unavailable` — `{"status":"not_ready", ...}` (other reasons)                         | Config invalid, token missing or validation failed, or process database unavailable. Check the server log.                                                                                                                                                                                     |
| Connection refused                                                                                | `SLABAPServer.exe` is not running. Start it first.                                                                                                                                                                                                                                             |

If the server returns `not_ready`:

* For `CONFIG_RESTART_REQUIRED`, see [Live reload and restart-required fields](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#live-reload-and-restart-required-fields).
* Confirm `slabapcli sealights test` succeeds.
* Check the server log at `public\logs\server-YYYYMMDD.log` for the startup error.
* Re-run `slabapcli setup status` for a comprehensive diagnostic report.

{% hint style="info" %}
The server binds to `127.0.0.1` (loopback) only and is not accessible from remote machines by design.
{% endhint %}

***

### Configuration Issues <a href="#configuration-issues" id="configuration-issues"></a>

#### Changes not taking effect <a href="#stale-server-configuration" id="stale-server-configuration"></a>

If a `config.toml` edit does not appear to take effect, confirm the active file path, check for TOML errors, and see [Live reload and restart-required fields](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#live-reload-and-restart-required-fields).

If `testrepo test` reports that the configured test repository was not available to the server (`TESTREPO_NOT_FOUND` / `TestrepoNotFound`), verify the `[[testrepo]]` entry in the active file, then re-run the printed `slabapcli testrepo test` command.

#### Config version too low — CLI refuses to start <a href="#config-version-too-low" id="config-version-too-low"></a>

If the CLI prints a message similar to:

```
Config version N is not supported (minimum: 4). Run the `slabapcli setup migrate` command to migrate your config.
```

Upgrade the configuration file to version 4:

{% tabs %}
{% tab title="Command Prompt" %}

```batch
slabapcli.exe setup migrate
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
.\slabapcli.exe setup migrate
```

{% endtab %}
{% endtabs %}

See [Migrate a legacy configuration](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/set-up-the-agent/migrate-a-legacy-configuration.md) for full details and the interactive `--yes` flag.

#### CLI command produces no log file <a href="#cli-no-log-file" id="cli-no-log-file"></a>

`slabapcli.exe` logs to the console only — no log file is written for any CLI command. To preserve CLI output, redirect it:

{% tabs %}
{% tab title="Command Prompt" %}

```batch
slabapcli.exe setup status > status.txt 2>&1
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
.\slabapcli.exe setup status *> status.txt
```

{% endtab %}
{% endtabs %}

For server-backed failures, start with the per-task folders under `public\logs\{taskType}\` — see [Server task logs](#server-task-logs). Watcher-local pipeline summaries live under `public\Logs\{pipeline}\`.

***

### Secrets and Credentials Issues <a href="#secrets-and-encryption" id="secrets-and-encryption"></a>

When `key` and `iv` in `[settings]` are empty, secrets — the SeaLights token, RFC passwords, and adapter credentials — are stored as **plaintext** in `config.toml`, and you can read and edit those values directly in the file. When `key` and `iv` are set, secrets are encrypted at rest; use the CLI `set` commands to update them.

#### Re-entering a secret credential <a href="#re-entering-secret" id="re-entering-secret"></a>

To update a single secret (for example, a changed RFC password) without re-running the full setup flow:

1. Re-run `slabapcli rfc set --name <name>` (or `testrepo set --name <name>`) — the command prompts for credentials interactively. Alternatively, edit the value directly in `config.toml`.
2. Confirm the change with `GET /ready` or by re-running the connection test.
3. If an already-running footprint or other scheduled task may still hold the prior credentials, stop and start that **task** as needed.

{% hint style="info" %}
Testrepo adapter **secret** fields (credentials such as `username`, `password`, `apikey`, `clientId`, `clientSecret`) **cannot be passed via `--setting`**. They must be entered interactively during `testrepo set`, or updated directly in `config.toml`. See [Configuration settings](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md) for which adapter fields are secrets.
{% endhint %}

***

### SAP System Errors <a href="#sap-system-errors" id="sap-system-errors"></a>

These errors originate from the SAP system side — RFC connectivity, user credentials, and authorization configuration. Use `slabapcli rfc test --name <rfc_name>` as a first diagnostic step.

#### E-001: RFC Communication Failure <a href="#e-001-rfc-communication-failure" id="e-001-rfc-communication-failure"></a>

**Error message:**

```
RFC error. rc='0' group='4' Description='Opening RFC connection <name>'
Key='RFC_COMMUNICATION_FAILURE'
```

**Cause:**

* The hostname configured for the RFC connection in `config.toml` is incorrect or unreachable.
* The target SAP system is currently down or unreachable.
* The RFC connection was unexpectedly disconnected (network issue, firewall, SAP router).
* The hostname points to a SAP message server (load balancer) rather than a direct application server. The SeaLights ABAP Agent requires a direct application server connection and does not support message server or logon group connections.

**Resolution:**

1. Verify the `hostname` and `sysnr` values in the `[[rfc]]` section of `config.toml`.
2. Confirm the SAP system is running (`SM51` or ping the host).
3. Check network connectivity and firewall rules for RFC port `33<sysnr>`.
4. If using a SAP router, verify the `router` string in `config.toml`.
5. Test the connection: `slabapcli rfc test --name <rfc_name>`.
6. If the hostname points to a message server, replace it with a direct application server hostname. Use transaction `SMGW` on the SAP system to identify the correct hostname and system number, then re-run:

```powershell
.\slabapcli.exe rfc set --name '<name>' --hostname '<app-server-hostname>' --sysnr '<sysnr>' --client '<client>' --lang 'EN'
```

***

#### E-002: RFC Logon Failure <a href="#e-002-rfc-logon-failure" id="e-002-rfc-logon-failure"></a>

**Error message:**

```
RFC error. rc='0' group='3' Description='Opening RFC connection <name>'
Key='RFC_LOGON_FAILURE'
Message='Name or password is incorrect (repeat logon)'.
```

**Cause:**

The `client`, `username`, or `password` specified in `config.toml` for the RFC connection is incorrect.

**Resolution:**

1. Verify the `client`, `username`, and `password` values in the `[[rfc]]` section.
2. Note that `username` and `password` are stored encrypted — use `slabapcli rfc set` to re-enter credentials if needed.
3. Check that the SAP user account is not locked (transaction `SU01`).
4. Confirm the user is authorized for the specified client.
5. Test the connection: `slabapcli rfc test --name <rfc_name>`.

***

#### E-003: RFC Authorization Missing — RFCPING <a href="#e-003-rfc-authorization-missing--rfcping" id="e-003-rfc-authorization-missing--rfcping"></a>

**Error message:**

```
RFC error. rc='0' group='2' Description='Opening RFC connection <name>'
Key='RFC_NO_AUTHORITY'
Message='No RFC authorization for function module RFCPING.'
```

**Cause:**

The RFC user is missing authorization object `S_RFC` with field `RFC_NAME = RFCPING`.

**Resolution:**

Add to the user's authorization role:

| Object  | Field      | Value     |
| ------- | ---------- | --------- |
| `S_RFC` | `RFC_NAME` | `RFCPING` |
| `S_RFC` | `ACTVT`    | `16`      |
| `S_RFC` | `RFC_TYPE` | `FUNC`    |

Activate the role and regenerate the user's authorization profile (transaction `SU01` > User tab > compare/regenerate, or `PFCG` to maintain the role).

For the complete `S_RFC` values required by `/TRICE/SL_AUTHS`, see [Generate Authorization Profiles](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/install-the-abap-agent/generate-authorization-profiles.md).

***

#### E-004: RFC Invalid Handle — Missing Function Metadata Authorization <a href="#e-004-rfc-invalid-handle--missing-function-metadata-authorization" id="e-004-rfc-invalid-handle--missing-function-metadata-authorization"></a>

**Error message:**

```
RFC error. rc='0' group='5' Description='RfcCreateFunction'
Key='RFC_INVALID_HANDLE'
Message='An invalid handle 'RFC_FUNCTION_DESC_HANDLE' was passed to the API call'
```

**Cause:**

The RFC user is missing authorization for one or both of these function modules:

* `DDIF_FIELDINFO_GET`
* `RFC_GET_FUNCTION_INTERFACE`

Without these, the agent cannot retrieve function module metadata needed to make subsequent RFC calls.

**Resolution:**

Add to the user's authorization role:

| Object  | Field      | Value                        |
| ------- | ---------- | ---------------------------- |
| `S_RFC` | `RFC_NAME` | `DDIF_FIELDINFO_GET`         |
| `S_RFC` | `RFC_NAME` | `RFC_GET_FUNCTION_INTERFACE` |
| `S_RFC` | `ACTVT`    | `16`                         |
| `S_RFC` | `RFC_TYPE` | `FUNC`                       |

These named modules address this error; they are not the complete `S_RFC` requirement. For the full `/TRICE/SL_AUTHS` role values, see [Generate Authorization Profiles](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/install-the-abap-agent/generate-authorization-profiles.md).

***

#### E-005: SeaLights Custom Authorization Missing <a href="#e-005-sealights-custom-authorization-missing" id="e-005-sealights-custom-authorization-missing"></a>

**Error message:**

```
RFC error. rc=5. Description=RfcCallReceiveAug. RfcInvoke ABAP Exception.
Key=NO_SEALIGHTS_AUTHORIZATION.
```

**Cause:**

The RFC user is missing the SeaLights custom authorization object `/TRICE/OBJ` with field `/TRICE/CMP = CORE` and activity `16` (Execute).

This object is part of the ABAP Addon and controls access to the SeaLights custom RFCs in the `/TRICE/` namespace.

**Resolution:**

Add to the user's authorization role:

| Object       | Field        | Value          |
| ------------ | ------------ | -------------- |
| `/TRICE/OBJ` | `/TRICE/CMP` | `CORE`         |
| `/TRICE/OBJ` | `ACTVT`      | `16` (Execute) |

Ensure the ABAP Addon is installed on the target system (via SAINT transaction) — this object is only available after addon installation.

***

#### E-006: Table Read Authorization Missing <a href="#e-006-table-read-authorization-missing" id="e-006-table-read-authorization-missing"></a>

**Error message:**

```
RFC error. rc='5' group='1' Description='RfcCallReceiveAug. RfcInvoke ABAP Exception'
Key='NO_AUTHORIZATION'
Message=' Number:000'
```

**Cause:**

The RFC user's authorization role is missing one or both of:

1. Authorization object `S_TABU_RFC` with field `ACTVT = 03` (Display).
2. Authorization object `S_TABU_NAM` with the required table names.

**Resolution:**

Add `S_TABU_RFC` with `ACTVT = 03` and `S_TABU_NAM` with `ACTVT = 03` plus the required table names to the role. For the complete table list and authorization values in `/TRICE/SL_AUTHS`, see [Generate Authorization Profiles](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/install-the-abap-agent/generate-authorization-profiles.md).

Activate the role and regenerate the user's authorization profile (transaction `SU01` > User tab > compare/regenerate, or `PFCG` to maintain the role).

***

#### E-007: PHD Database Error — ST03 Data Not Available <a href="#e-007-phd-database-error--st03-data-not-available" id="e-007-phd-database-error--st03-data-not-available"></a>

**Error message:**

```
Exception: ExecCmd3. db=<rfc_name>_PHD err=file is not a database
- SELECT sql FROM sqlite_master WHERE tbl_name = 'AppArch' AND type = 'table'.
```

**Cause:**

The ST03 workload statistics collector is not running on the SAP PRD system. During build mapping, the agent reads Performance History Data (PHD) from the PRD system to determine which packages and modules are actively used. When ST03 data is not available, the PHD database file is empty or corrupted.

**How to diagnose:**

The buildmap process restarts repeatedly. Check the failing IBM stage under `public\logs\` (often `sync_phd` or a later stage) for that day’s `{processId}` — `{processId}.log` and `agent.log`. The watcher summary `public\Logs\{pipeline}\InitialBuildMapping_YYYY-MM-DD.log` may show the same error on each restart.

**Resolution:**

1. Log in to the SAP PRD system and run transaction **ST03** (or **ST03N**).
2. Verify that the workload statistics collector is active. If not, start it.
3. Ensure data has been collected for the retention period configured in `config.toml` under `[rfcdata.prd] retentionperiod`.
4. After ST03 is running and data is available, delete the corrupted PHD database file from the agent's private data directory (see [Configuration settings](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md) for database locations) and re-run the buildmap:

{% tabs %}
{% tab title="Command Prompt" %}

```batch
slabapcli.exe buildmap run --pipeline <name>
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
.\slabapcli.exe buildmap run --pipeline <name>
```

{% endtab %}
{% endtabs %}

Alternatively, if ST03 cannot be enabled on the PRD system, export ST03 data manually from the SAP GUI and use the PHD import feature:

```batch
slabapcli.exe rfc phd --rfc <non_prod_rfc_name> --prd <prd_name> --dir <path_to_exported_files>
```

{% hint style="info" %}
`rfc phd` requires the non-production RFC Destination (`--rfc`, also accepted as `--dev`/`--qas`), the PRD system name (`--prd`), and the directory containing the exported ST03 files (`--dir`). See [Upload usage data to an RFC Destination](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/upload-usage-data-to-an-rfc-destination.md).
{% endhint %}

***

#### ABAP Addon Not Installed <a href="#abap-addon-not-installed" id="abap-addon-not-installed"></a>

If you see `NO_SEALIGHTS_AUTHORIZATION` or errors referencing `/TRICE/` function modules:

1. Verify the addon is installed: check transaction `SAINT` on the target SAP system.
2. The addon package files (`*.SAR`, `*.PAT`) are provided in the `abap_addon/` directory of the agent distribution.
3. The addon must be installed on **both** QAS and PRD systems referenced in the pipeline.

***

### Diagnosing SAP Authorization Role Issues <a href="#diagnosing-sap-authorization-role-issues" id="diagnosing-sap-authorization-role-issues"></a>

The agent requires the SAP role **`/TRICE/SL_AUTHS`** assigned to the RFC user. Verify that the generated role matches the authorization objects and values listed in [Generate Authorization Profiles](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/install-the-abap-agent/generate-authorization-profiles.md).

***

### SeaLights Connection Errors <a href="#sealights-connection-errors" id="sealights-connection-errors"></a>

These errors relate to the agent's communication with the SeaLights API. Use `slabapcli sealights test` as a first diagnostic step.

#### E-008: SSL Certificate Verification Failed <a href="#e-008-ssl-certificate-verification-failed" id="e-008-ssl-certificate-verification-failed"></a>

**Error message (from `slabapcli sealights test`):**

```
Failed to get apps. Http error: SSL server verification failed
Verify error: unable to get local issuer certificate
```

**Cause:**

The agent cannot verify the SSL certificate of the SeaLights API endpoint. This typically occurs when:

* The agent host is behind a corporate proxy or firewall that performs SSL inspection.
* The SeaLights API uses a certificate signed by an internal or private Certificate Authority not in the system's trust store.
* The Windows certificate store is missing intermediate or root CA certificates.

**Resolution:**

Add the following section to `config.toml` to disable SSL certificate verification:

```toml
[http]
disableSslCheck = true
```

{% hint style="warning" %}
Disabling SSL verification reduces transport security. Use this as a workaround in controlled environments. The preferred long-term fix is to install the required CA certificates into the Windows trust store.
{% endhint %}

***

#### SeaLights API Connectivity <a href="#sealights-api-connectivity" id="sealights-api-connectivity"></a>

Test the connection to the SeaLights backend:

```batch
slabapcli.exe sealights test
```

If this fails, check:

* The `token` in `[sealights]` configuration is valid and not expired.
* HTTPS outbound access to SeaLights API endpoints is not blocked.
* If using a proxy, verify `[proxy]` settings in `config.toml`.
* If the error mentions SSL certificate verification, see [E-008](#e-008-ssl-certificate-verification-failed).

***

### General Troubleshooting <a href="#general-troubleshooting" id="general-troubleshooting"></a>

#### Verifying Configuration <a href="#verifying-configuration" id="verifying-configuration"></a>

List the current agent configuration to confirm settings are loaded correctly:

```batch
slabapcli.exe rfc list
slabapcli.exe pipeline list
slabapcli.exe testrepo list
slabapcli.exe sealights test
```

#### Windows Task Scheduler Issues <a href="#windows-task-scheduler-issues" id="windows-task-scheduler-issues"></a>

The agent schedules background tasks via Windows Task Scheduler. If tasks are not running:

1. Open Task Scheduler (`taskschd.msc`) and look for SeaLights tasks.
2. Verify the agent was configured with administrative privileges.
3. Check the task history for failure reasons and exit codes.
4. Re-schedule: `slabapcli buildmods run --pipeline <name>`.

**Watcher Exit Codes**

| Exit code | Meaning                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`       | Success.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `1`       | General failure — check the watcher log for details.                                                                                                                                                                                                                                                                                                                                                                  |
| `10`      | Another watcher for the same action is already running. Wait for it to complete, or stop it first.                                                                                                                                                                                                                                                                                                                    |
| `11`      | Build-mode conflict — `INIT_BUILD_MAP`, `BUILD_MODS`, and `REFRESH_LINKS` are mutually exclusive for the same pipeline. Stop the conflicting build-mode task, wait for any running watcher to finish, then retry or run [refresh links](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/command-line-interface/refresh-links.md) before restarting Build Modifications monitoring. |
| `12`      | Server unreachable — `SLABAPServer.exe` is not running or not responding. Start the server and confirm `GET /ready` returns `200`.                                                                                                                                                                                                                                                                                    |
| `13`      | Configuration resolution error — bad configuration or credentials. Verify the active `config.toml` and credentials. See [Live reload and restart-required fields](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/configuration-settings.md#live-reload-and-restart-required-fields) if `/ready` reports `CONFIG_RESTART_REQUIRED`.                                                |
| `14`      | Task execution error — the task ran but ended in an error state. For server-backed actions, open `public\logs\{taskType}\{date}\{processId}\`; for Build Mods / Footprints, check `public\Logs\{pipeline}\`.                                                                                                                                                                                                          |
| `15`      | Upload error — the task's data upload to SeaLights failed. Verify the token (`slabapcli sealights test`) and network/proxy settings.                                                                                                                                                                                                                                                                                  |
| `16`      | Dependency not met — a prerequisite step has not completed (for example, an initial build map before build modifications).                                                                                                                                                                                                                                                                                            |
| `17`      | Server lock conflict — another operation holds the lock (HTTP 409). Retry once the in-progress operation finishes.                                                                                                                                                                                                                                                                                                    |
| `18`      | Task timeout — the task exceeded its maximum allowed duration. Check the matching server task folder under `public\logs\{taskType}\` when the action is server-backed.                                                                                                                                                                                                                                                |
| `19`      | Malformed response — the server returned an unparseable response. Check `public\logs\server-YYYYMMDD.log` and the task’s `{processId}.log`.                                                                                                                                                                                                                                                                           |

{% hint style="success" %}
When you stop or replace a scheduled task via `slabapcli`, the agent automatically terminates any running watcher process for that task. Orphaned watcher processes are not possible.
{% endhint %}

***

### Quick Diagnostic Checklist <a href="#quick-diagnostic-checklist" id="quick-diagnostic-checklist"></a>

Use this checklist when onboarding a new SAP system or diagnosing an unexpected failure:

* ABAP Addon is installed on the SAP system (QAS and PRD)
* SAP system is reachable from the agent host (ping / telnet port 33xx)
* RFC user exists and is not locked (`SU01`)
* Role `/TRICE/SL_AUTHS` is assigned to the RFC user
* Authorization profile is regenerated after role assignment
* ST03 process is enabled on the SAP PRD system
* SCMON process is enabled on the SAP QAS system
* `slabapcli rfc test --name <rfc_name>` succeeds for every onboarded RFC
* `slabapcli sealights test` succeeds
* `GET http://127.0.0.1:17500/ready` returns `200 OK`
* `slabapcli setup status` exits with code `0`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/abap-agent-2.0/troubleshooting-the-abap-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.