# Troubleshooting the ABAP Agent

### 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 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` with correct RFC, pipeline, and SeaLights settings

***

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

After initial onboarding, the agent's core operations (build mapping, build modifications, footprint collection) run as **Windows Scheduled Tasks** in the background. There is no interactive console output for these tasks. **Logs are the primary tool for diagnosing issues** once the agent is onboarded and running.

#### Log File Location <a href="#log-file-location" id="log-file-location"></a>

Log files are written to:

```
{userData}/public/{PIPELINE_NAME}/{TASK_NAME}_{DATE}.log
```

Where:

* `{userData}` is the `userdata` path configured in the `[settings]` section of `config.toml` (default: `../userData` relative to the install directory).
* `{PIPELINE_NAME}` is the pipeline name as defined in `[[pipeline]]` in `config.toml`.
* `{TASK_NAME}` is the agent action: `INIT_BUILD_MAP`, `BUILD_MODS`, or `FOOTPRINTS`.
* `{DATE}` is the date the log was created.

**Example paths:**

```
C:\apps\SLABAPAgent\userData\public\my-pipeline\INIT_BUILD_MAP_2026-03-06.log
C:\apps\SLABAPAgent\userData\public\my-pipeline\BUILD_MODS_2026-03-06.log
C:\apps\SLABAPAgent\userData\public\my-pipeline\FOOTPRINTS_2026-03-06.log
```

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

The log level 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 (only relevant for interactive CLI commands)
flushinterval = 5        # Seconds between flush to disk
flushlevel = "info"      # Minimum level that triggers immediate flush
retentionperiod = 14     # Days to keep log files
```

For troubleshooting, temporarily increase the log level to `debug` or `trace` to capture detailed RFC calls, HTTP requests, and data processing steps. Remember to set it back to `info` after resolving the issue to avoid excessive log growth. You will need to restart any scheduled jobs currently running.

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

When a scheduled task fails or produces unexpected results, check the corresponding log file for:

* **`[error]`** lines — direct error messages with exception details and source file references.
* **RFC errors** — connection, authorization, and data retrieval failures (see [SAP System Errors](https://file+.vscode-resource.vscode-cdn.net/Users/avichaishapira/GitHub/SeaLights/agents/SL.OnPremise.Agents.ABAP/doc/troubleshooting.md#sap-system-errors) below).
* **HTTP errors** — SeaLights API communication failures, SSL issues, or token problems (see [SeaLights Backend Errors](https://file+.vscode-resource.vscode-cdn.net/Users/avichaishapira/GitHub/SeaLights/agents/SL.OnPremise.Agents.ABAP/doc/troubleshooting.md#sealights-backend-errors) below).
* **Repeated restarts** — if the same task keeps restarting and logging the same error, it indicates a persistent configuration or authorization issue that requires manual intervention.

#### Log Rotation <a href="#log-rotation" id="log-rotation"></a>

Logs are rotated daily. Old log files are automatically purged after the configured `retentionperiod` (default: 14 days) when the `purgelogs` task is scheduled:

```
slabapcli purgelogs run
```

***

### 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. This role contains the following authorization objects:

#### `/TRICE/OBJ` — SeaLights Custom Authorization <a href="#triceobj--sealights-custom-authorization" id="triceobj--sealights-custom-authorization"></a>

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

#### `S_RFC` — RFC Function Module Access <a href="#s_rfc--rfc-function-module-access" id="s_rfc--rfc-function-module-access"></a>

| Field      | Values                          |
| ---------- | ------------------------------- |
| `ACTVT`    | `*` (All)                       |
| `RFC_TYPE` | `FUNC`                          |
| `RFC_NAME` | `/TRICE/*`                      |
|            | `DDIF_FIELDINFO_GET`            |
|            | `GET_SYSTEM_TIME_REMOTE`        |
|            | `RFCPING`                       |
|            | `RFC_GET_FUNCTION_INTERFACE`    |
|            | `RFC_GET_TABLE_ENTRIES`         |
|            | `RFC_SYSTEM_INFO`               |
|            | `SCMON_COLLECT`                 |
|            | `SWNC_COLLECTOR_GET_AGGREGATES` |
|            | `SWNC_COLLECTOR_STARTER`        |

#### `S_TABU_NAM` — Table Name Access <a href="#s_tabu_nam--table-name-access" id="s_tabu_nam--table-name-access"></a>

| Field   | Values                                                                                                                                              |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACTVT` | `03` (Display)                                                                                                                                      |
| `TABLE` | `DD03L`, `O2APPL`, `SCMON_CONFIG`, `SCMON_VDATA`, `SPROXREG`, `TADIR`, `TFDIR`, `TMDIR`, `TRDIR`, `TSTC`, `TSTCP`, `TTZCU`, `WBCROSSGT`, `WBCROSSI` |

#### `S_TABU_RFC` — RFC Table Access <a href="#s_tabu_rfc--rfc-table-access" id="s_tabu_rfc--rfc-table-access"></a>

| Field   | Value          |
| ------- | -------------- |
| `ACTVT` | `03` (Display) |

***

### 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 used for load balancing, replace it with the hostname of a specific application server instance. Use transaction `SMGW` on the SAP system to identify the correct application server 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. Remember 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`    | `*`       |
| `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).

***

#### 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` |

***

#### 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 = 33` (Read via RFC).
2. Authorization object `S_TABU_NAM` with the required table names.

The agent reads the following SAP tables during build mapping and footprint collection:

| Table          | Purpose                                         |
| -------------- | ----------------------------------------------- |
| `DD03L`        | Data Element Field Definitions                  |
| `TADIR`        | Object Directory — lists all repository objects |
| `TFDIR`        | Function Module Directory                       |
| `TMDIR`        | Method Directory (class methods)                |
| `TRDIR`        | Program Directory (report attributes)           |
| `TSTC`         | Transaction Codes                               |
| `TSTCP`        | Transaction Code Parameters                     |
| `TTZCU`        | Transaction Code Usage                          |
| `WBCROSSGT`    | Cross-Reference (where-used)                    |
| `WBCROSSI`     | Include Cross-Reference                         |
| `O2APPL`       | BSP Application Directory                       |
| `SCMON_CONFIG` | SCMON configuration data                        |
| `SCMON_VDATA`  | SCMON coverage data                             |
| `SPROXREG`     | Service/Proxy Registry                          |

**Resolution:**

Add both authorization objects to the role:

**Object 1 — `S_TABU_RFC`:**

| Field   | Value |
| ------- | ----- |
| `ACTVT` | `33`  |

**Object 2 — `S_TABU_NAM`:**

| Field   | Value          |
| ------- | -------------- |
| `ACTVT` | `03`           |
| `TABLE` | `DD03L`        |
| `TABLE` | `O2APPL`       |
| `TABLE` | `SCMON_CONFIG` |
| `TABLE` | `SCMON_VDATA`  |
| `TABLE` | `SPROXREG`     |
| `TABLE` | `TADIR`        |
| `TABLE` | `TFDIR`        |
| `TABLE` | `TMDIR`        |
| `TABLE` | `TRDIR`        |
| `TABLE` | `TSTC`         |
| `TABLE` | `TSTCP`        |
| `TABLE` | `TTZCU`        |
| `TABLE` | `WBCROSSGT`    |
| `TABLE` | `WBCROSSI`     |

***

#### 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'.
Thrown at C:\projectFiles\src\libs\table\DbSqliteConnection.cpp:666
```

**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, causing this error.

**How to diagnose:**

The buildmap process restarts repeatedly and this error appears in the agent logs each time.

**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 `{userData}/{pipeline}/` and re-run the buildmap: `slabapcli buildmap run --pipeline <name>`.

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

```
slabapcli rfc phd --name <rfc_name> --dir <path_to_exported_files>
```

***

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

***

### 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 (man-in-the-middle).
* 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
```

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

***

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

Test the connection to the SeaLights backend:

```
slabapcli 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](https://file+.vscode-resource.vscode-cdn.net/Users/avichaishapira/GitHub/SeaLights/agents/SL.OnPremise.Agents.ABAP/doc/troubleshooting.md#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:

```
slabapcli rfc list
slabapcli pipeline list
slabapcli 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 run with administrative privileges.
3. Check the task history for failure reasons.
4. Re-schedule: `slabapcli buildmods run --pipeline <name>`.

***

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

Use this checklist when onboarding a new SAP system:

* ABAP Addon is installed on SAP system
* 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 SAP system
* SCMON process is enabled on SAP system
* `slabapcli rfc test` succeeds for every onboarded RFC


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.