> For the complete documentation index, see [llms.txt](https://sealights-docs.tricentis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sealights-docs.tricentis.com/setup-and-configuration/troubleshooting-the-abap-agent.md). # Troubleshooting the ABAP Agent Common errors during ABAP Agent 2.1 onboarding and operation — diagnostics for the server, configuration, SAP authorizations, and SeaLights connectivity. {% 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](broken://pages/A8FSceuQXginyDTL5f4z). {% endhint %} ### Prerequisites 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 Add-on**: 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 6, with correct RFC, pipeline, and SeaLights settings *** ### Agent Logs Once the agent is onboarded, **server task logs** are the primary place to diagnose failures for Initial Build Map, Build Modifications, test-repository search/test, and other server-backed work. Watcher-local pipeline logs (for example Footprints) and CLI console output are secondary. Default userdata root: `%ProgramData%\Tricentis\SeaLights\ABAP Agent` (override with `[settings].userdata`). All components write logs under `public\Logs`. Field reference and full inventory: [Configuration settings — Log locations](broken://pages/DZM4uWEu5r51kMDWCmDB#log-locations). #### Server task logs (start here) When a **server-backed** task fails, open the run folder under the pipeline's logs first: ``` {userdata}\public\Logs\{pipeline}\{origin}\{yyyy-MM-dd}\{run}\ ``` Test-repository tasks (`search_testrepo`, `test_testrepo`) add the test repository name before the run folder: ``` {userdata}\public\Logs\{pipeline}\{origin}\{yyyy-MM-dd}\{testrepo}\{run}\ ``` | Path piece | Meaning | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | | `{pipeline}` | Pipeline name (the RFC Destination name for tasks not tied to a pipeline, such as `upload_flpca`) | | `{origin}` | The action that started the task — see the table below | | `{yyyy-MM-dd}` | UTC date when the task started | | `{testrepo}` | Test repository name (test-repository tasks only) | | `{run}` | Watcher run ID — all server tasks from one watcher run share this folder. One-off CLI tasks use the task's `processId`. | Inside that folder, each server task writes its own set of files: | File | Contents | Config lever | | ------------------------------------ | ---------------------------------------------------------- | ------------------------------- | | `{taskType}_{processId}.log` | Server-side orchestration for that task | `[server.logging].defaultLevel` | | `{taskType}_{processId}_agent.log` | Native CAPI / `slabap.agent.dll` work for that task | `[logging]` (native) | | `{taskType}_{processId}_adapter.log` | Adapter host / external tool calls (when AdapterHost runs) | `[adapters].logLevel` | | `{taskType}_{processId}_worker.log` | Adapter worker process (OpenText ALM) | `[adapters].logLevel` | **Where to look first when a server task fails** 1. Open `public\Logs\{pipeline}\` and the `{origin}` folder for the failing action (table below). 2. Open today’s (or the failure day’s) `{yyyy-MM-dd}` directory. 3. Pick the `{run}` subfolder for the failed run — use the newest folder if you are unsure. For test-repository work, open the `{testrepo}` folder first. 4. Find the failing stage by its `{taskType}` file name prefix and read `{taskType}_{processId}.log` and `{taskType}_{processId}_agent.log` side by side. For test-repository work, also open `{taskType}_{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, read it from the end of the per-task log file name, or use the `processId` printed in watcher/CLI task output. **Common origin folders** | Watcher / CLI action | `{origin}` folder | Task files in the run folder | | -------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | | `INIT_BUILD_MAP` (Initial Build Map) | `InitialBuildMap` | `generate_cache` → `sync_phd` → `generate_links` → `generate_graph` → `generate_buildmap` (one set of files per stage) | | `BUILD_MODS` | `BuildMods` | `query_transports`, `generate_cache`, `generate_links`, `generate_graph`, `generate_buildmods` | | `SEARCH_TESTREPO` | `SearchTestRepo` | `search_testrepo` (under `{testrepo}\`) | | `slabapcli testrepo test` (and auto-test after `testrepo set`) | `TestTestRepo` | `test_testrepo` (under `{testrepo}\`) | | `upload_flpca import` | `UploadFlpca` | `upload_flpca` | IBM stage roles: [Create an Initial Build Map for your Pipeline](broken://pages/6f4WDLP7ZxZdqhvqwcMb). The server also writes a daily host log at `{userdata}\public\Logs\server-YYYYMMDD.log` (startup, readiness, and task lifecycle). Use it to find `processId` or diagnose “server won’t start / returns 503”. #### Which log to open (symptom → log) | Symptom | Start here | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Initial build map fails, stalls, or restarts | `public\Logs\{pipeline}\InitialBuildMap\{date}\{run}\` — the failing stage’s `{taskType}_{processId}.log` and `{taskType}_{processId}_agent.log`. Optionally skim `public\Logs\{pipeline}\InitialBuildMapping_YYYY-MM-DD.log` for watcher orchestration context. | | Build modifications fail | `public\Logs\{pipeline}\BuildMods\{date}\{run}\` — the failing stage’s task logs. Optionally skim `public\Logs\{pipeline}\BuildMods_YYYY-MM-DD.log`. | | `testrepo test` fails | `public\Logs\{pipeline}\TestTestRepo\{date}\{testrepo}\{processId}\` — `test_testrepo_{processId}.log` and `test_testrepo_{processId}_adapter.log` | | Test-repository search / recommended tests fail | `public\Logs\{pipeline}\SearchTestRepo\{date}\{testrepo}\{run}\` — `search_testrepo_{processId}.log` and `search_testrepo_{processId}_adapter.log` | | Adapter auth, proxy, or tool API errors | Prefer `{taskType}_{processId}_adapter.log` in the same task folder; raise `[adapters].logLevel` if needed | | FLPCA upload import fails | `public\Logs\{rfc}\UploadFlpca\{date}\{processId}\upload_flpca_{processId}.log` (and `upload_flpca_{processId}_agent.log` if present) | | `upload critical_list` fails | `public\Logs\{pipeline}\DirectApi\{date}\{processId}\upload_critical_list_{processId}.log`. For the messages the command prints, see [Upload a Critical List](broken://pages/RyMh0JbwIMIXBvLuyPT5). | | Server won’t start or returns 503 | `public\Logs\server-YYYYMMDD.log` | | 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) 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`, `BuildMods_YYYY-MM-DD.log`, `Footprints_YYYY-MM-DD.log` | | Watcher bootstrap (`main_logger`) | `%ProgramData%\Tricentis\SeaLights\ABAP Agent\public\Logs\watcher\main_logger__.log` (always under ProgramData, even if userdata is relocated) | | Purger (`purger.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; Footprints writes only the watcher-local pipeline daily log. {% endhint %} #### Log Levels 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 (`{taskType}_{processId}.log`) use `[server.logging].defaultLevel`. Adapter host logs (`{taskType}_{processId}_adapter.log`) use `[adapters].logLevel`. Field reference: [Configuration settings](broken://pages/DZM4uWEu5r51kMDWCmDB#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 When a server-backed task fails, open that run’s `public\Logs\{pipeline}\{origin}\{date}\{run}\` folder and check: * **`[error]`** lines in `{taskType}_{processId}.log` and `{taskType}_{processId}_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 `{taskType}_{processId}.log` looks fine but the external tool call failed, open `{taskType}_{processId}_adapter.log` (and the reverse if AdapterHost never started). * **Repeated restarts** — the same stage failing again in successive runs indicates a persistent configuration or authorization issue. For watcher-local Footprints, use the same checks in the pipeline daily log under `public\Logs\{pipeline}\`. *** ### Server Issues The ABAP Agent server runs as the **SeaLights ABAP Server** Windows service (`SLABAPServer`), bound to `http://127.0.0.1:17500`. Start and stop it with `slabapcli server start` and `slabapcli server stop`. See [Start the ABAP Agent Server](broken://pages/jjXJbDJ9CnFBYzl2NDMP) for the full lifecycle and CLI reference. The SeaLights token (`sealights.token`) is **cold** — the server reads it when the service starts. Set it with `slabapcli sealights set` before the first start (if it is missing, the server starts but reports `not_ready`); changing it requires `slabapcli server stop` then `slabapcli server start`. #### Server won't start or exits immediately **Symptoms:** `slabapcli server start` fails, the `SLABAPServer` service does not reach a running state, or `slabapcli server status` reports not ready. **Diagnostic steps:** 1. Check the server log for the startup error (`{userdata}` defaults to `%ProgramData%\Tricentis\SeaLights\ABAP Agent`). For the `Error:` messages that `slabapcli server start` prints, see [Start the ABAP Agent Server](broken://pages/jjXJbDJ9CnFBYzl2NDMP). ``` {userdata}\public\Logs\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 set` (if not yet done), then `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](broken://pages/DZM4uWEu5r51kMDWCmDB). #### Server not reachable or returns 503 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 the service: `slabapcli server stop`, then `slabapcli server start`. See [Live reload and restart-required fields](broken://pages/DZM4uWEu5r51kMDWCmDB#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 | The `SLABAPServer` service is not running. Run `slabapcli server start` first. | If the server returns `not_ready`: * For `CONFIG_RESTART_REQUIRED`, see [Live reload and restart-required fields](broken://pages/DZM4uWEu5r51kMDWCmDB#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 #### Changes not taking effect 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](broken://pages/DZM4uWEu5r51kMDWCmDB#live-reload-and-restart-required-fields). If `testrepo test` prints `Connection test could not use the server's stale configuration.` followed by `Restart the ABAP Agent server, then run:` and a `slabapcli testrepo test` command, restart the server (`slabapcli server stop`, then `slabapcli server start`) and re-run the printed command. If it still fails, verify the `[[testrepo]]` entry in the active file. #### Config version too low — CLI refuses to start If the CLI prints a message similar to: ``` Config version N is not supported (minimum: 6). Run the `slabapcli setup migrate` command to migrate your config. ``` Upgrade the configuration file to the current version (6): {% 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](broken://pages/NRR5ldRJ84vbe7IcN65N) for full details and the interactive `--yes` flag. #### CLI command produces no log file `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\{pipeline}\{origin}\` — see [Server task logs](#server-task-logs). Watcher-local pipeline summaries live under `public\Logs\{pipeline}\`. *** ### Secrets and Credentials Issues 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 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 ` (or `testrepo set --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](broken://pages/DZM4uWEu5r51kMDWCmDB) for which adapter fields are secrets. {% endhint %} *** ### SAP System Errors These errors originate from the SAP system side — RFC connectivity, user credentials, and authorization configuration. Use `slabapcli rfc test --name ` as a first diagnostic step. #### E-001: RFC Communication Failure **Error message:** ``` RFC error. rc='0' group='4' Description='Opening RFC connection ' 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`. 4. If using a SAP router, verify the `router` string in `config.toml`. 5. Test the connection: `slabapcli rfc test --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 '' --hostname '' --sysnr '' --client '' --lang 'EN' ``` *** #### E-002: RFC Logon Failure **Error message:** ``` RFC error. rc='0' group='3' Description='Opening RFC connection ' 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 `. *** #### E-003: RFC Authorization Missing — RFCPING **Error message:** ``` RFC error. rc='0' group='2' Description='Opening RFC connection ' 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](broken://pages/JfFkO1xqq9huG22WXqhI). *** #### E-004: RFC Invalid Handle — Missing Function Metadata Authorization **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](broken://pages/JfFkO1xqq9huG22WXqhI). *** #### E-005: SeaLights Custom Authorization Missing **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 add-on 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 add-on is installed on the target system (via SAINT transaction) — this object is only available after add-on installation. *** #### E-006: Table Read Authorization Missing **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](broken://pages/JfFkO1xqq9huG22WXqhI). 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 **Error message:** ``` Exception: ExecCmd3. db=_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\{pipeline}\InitialBuildMap\{date}\{run}\` (often `sync_phd` or a later stage) — `{taskType}_{processId}.log` and `{taskType}_{processId}_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](broken://pages/DZM4uWEu5r51kMDWCmDB) for database locations) and re-run the buildmap: {% tabs %} {% tab title="Command Prompt" %} ```batch slabapcli.exe buildmap run --pipeline ``` {% endtab %} {% tab title="PowerShell" %} ```powershell .\slabapcli.exe buildmap run --pipeline ``` {% 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 --prd --dir ``` {% 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](broken://pages/fw9npSbrE9ByW6ww8CGd). {% endhint %} *** #### ABAP Add-on Not Installed If you see `NO_SEALIGHTS_AUTHORIZATION` or errors referencing `/TRICE/` function modules: 1. Verify the add-on is installed: check transaction `SAINT` on the target SAP system. 2. The add-on package files (`*.SAR`, `*.PAT`) are provided in the `abap_addon/` directory of the agent distribution. 3. The add-on must be installed on **both** QAS and PRD systems referenced in the pipeline. *** ### Diagnosing SAP Authorization Role Issues 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](broken://pages/JfFkO1xqq9huG22WXqhI). *** ### SeaLights Connection Errors 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 **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 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). *** ### Build Modification and Upload Issues | Symptom | Cause and what to do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A `BUILD_MODS` run fails with a message that ends in `no fallback start time: No SeaLights build found for /.` | The agent has no history of its own for the pipeline (first run after an installation or upgrade), and SeaLights has no build of the app to start from. Create the Initial Build Map first, and check the pipeline's app name and branch. See [Where monitoring resumes](broken://pages/JZVVGs3ieGcAwmbZ8qqj#where-monitoring-resumes). | | The run fails with a message that ends in `no fallback start time: None of the latest SeaLights build(s) for / has scan status 'Completed' yet.` | Same situation, but none of the latest 50 builds has finished scanning in SeaLights. Wait until one build shows scan status `Completed`; the next scheduled run continues on its own. | | The run fails with a message that ends in `no fallback start time: Could not reach SeaLights to resolve a fallback transport start time for / after attempt(s) (status , ).` | The agent could not read the latest builds from SeaLights. Check the token (`slabapcli sealights test`) and your network or proxy settings. The next scheduled run tries again. | | The run fails with a message that ends in `no fallback start time: Backend build '' has an invalid datetime format.` | The name of the newest build of the app has no date and time in the `\|` format, which usually means it was not created by the agent. Contact SeaLights support. | | A `BUILD_MODS` run fails with `PHD artifact '' does not exist.` | The production usage data for the pipeline's PRD RFC Destination is missing (for example, it was deleted). Build Modifications need it to select the packages to include. Run `slabapcli buildmap run` to create it again. If the pipeline uses imported usage data, run `slabapcli rfc phd` first. | | A transport shows no Build Modifications, or fewer than you expect | Build Modifications only include objects in the packages that the Initial Build Map covers, plus customer packages (names starting with `Z` or `Y`). Deleted objects are not limited. See [Which objects are included](broken://pages/JZVVGs3ieGcAwmbZ8qqj#which-objects-are-included). | | Transports imported earlier are not reported in one run | A scheduled run collects at most `[buildmods].maxtransportsperquery` transports (default `100`); the rest follow in the next runs. See [Configuration settings](broken://pages/DZM4uWEu5r51kMDWCmDB#buildmods). | | A transport whose upload failed is not reported | A transport is only recorded as processed after its upload succeeds, so the next scheduled run collects it again. If it keeps failing, check the token, your network or proxy settings, and the run's task logs. | | A SeaLights process (test-repository or impacted-graph upload) shows `ERROR` after an upload failure | The upload ended in an error that is not retried again: a permanent failure (for example HTTP 403 on the upload), all retry attempts used, or an upload that was interrupted when the server stopped. The agent then also reports the SeaLights process as `ERROR`, so the failure is visible in SeaLights. Uploads are retried up to `[server.uploadRetry].maxAttempts` times (default `2`; `0` means unlimited) — see [Configuration settings](broken://pages/DZM4uWEu5r51kMDWCmDB). Open the task log of the failed run (see [Server task logs](#server-task-logs)), fix the cause (token, network, proxy), and run the action again. | *** ### General Troubleshooting #### Verifying Configuration 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 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 `. **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` and `BUILD_MODS` are mutually exclusive for the same pipeline. Stop the conflicting build-mode task, wait for any running watcher to finish, then retry. | | `12` | Server unreachable — the `SLABAPServer` service is not running or not responding. Run `slabapcli server start` and confirm `slabapcli server status` or `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](broken://pages/DZM4uWEu5r51kMDWCmDB#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 the run folder under `public\Logs\{pipeline}\{origin}\{date}\`; for 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 watcher waited 1000 hours for a single server task and it still had not finished. The limit applies to each task separately and cannot be configured. Check the matching run folder under `public\Logs\{pipeline}\{origin}\` 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 `{taskType}_{processId}.log`. | {% hint style="info" %} When you stop or replace a scheduled task via `slabapcli`, the agent disables the task, asks Task Scheduler to stop any running instance, waits up to 10 seconds for the watcher to exit, and then deletes the task. If the watcher has not exited by then, the agent logs a warning that a watcher instance may still be running; check for a leftover `watcher.exe` process. {% endhint %} *** ### Quick Diagnostic Checklist Use this checklist when onboarding a new SAP system or diagnosing an unexpected failure: * ABAP add-on 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 ` succeeds for every onboarded RFC * `slabapcli sealights test` succeeds * `slabapcli server status` succeeds, or `GET http://127.0.0.1:17500/ready` returns `200 OK` * `slabapcli setup status` exits with code `0`