Ctrlk
Contact SupportProduct
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Troubleshooting the ABAP Agent

Common errors during ABAP Agent 2.0 onboarding and operation — diagnostics for the server, configuration, SAP authorizations, and SeaLights connectivity.

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.

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

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.

Server task logs (start here)

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. Refresh Links: Refresh links and impacted graph.

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)

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)

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

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.

Log Levels

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

Server per-task logs ({processId}.log) use [server.logging].defaultLevel. Adapter host logs ({processId}_adapter.log) use [adapters].logLevel. Field reference: Configuration settings.

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\{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 below).

  • HTTP errors — SeaLights API communication failures, SSL issues, or token problems (see 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

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 for startup instructions.

Server won't start or exits immediately

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

Diagnostic steps:

  1. Check the server log for the startup error:

    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:

If port 17500 is in use, stop the conflicting process or change the server port in config.toml (field [server].port). See Configuration settings.

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:

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.

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.

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

The server binds to 127.0.0.1 (loopback) only and is not accessible from remote machines by design.

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.

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

If the CLI prints a message similar to:

Upgrade the configuration file to version 4:

See Migrate a legacy configuration 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:

For server-backed failures, start with the per-task folders under public\logs\{taskType}\ — see 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 <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.

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 for which adapter fields are secrets.

SAP System Errors

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

Error message:

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:

E-002: RFC Logon Failure

Error message:

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

Error message:

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.

E-004: RFC Invalid Handle — Missing Function Metadata Authorization

Error message:

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.

E-005: SeaLights Custom Authorization Missing

Error message:

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

Error message:

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.

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:

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 for database locations) and re-run the buildmap:

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

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.

ABAP Addon Not Installed

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

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.

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):

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:

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

Test the connection to the SeaLights backend:

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.

General Troubleshooting

Verifying Configuration

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

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

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.

Quick Diagnostic Checklist

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

PreviousUninstall ABAP AgentNextABAP Agent 1.x

Last updated

Was this helpful?