> 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/command-line-interface/set-up-the-agent/migrate-a-legacy-configuration.md).

# Migrate a legacy configuration

Use this page when you are already on **ABAP Agent 2.0** (or installing a newer 2.0 build) and your `config.toml` is below **configuration schema version 6**.

{% hint style="warning" %}
**This is not the 1.3 → 2.0 product migration.** `setup migrate` upgrades the **2.0+ configuration schema** only. If you are moving from ABAP Agent 1.3 or earlier to 2.0, see [Compatibility with earlier ABAP Agent versions](broken://pages/gzlcIedoaqgX25KaIvmi#compatibility-with-earlier-abap-agent-versions).
{% endhint %}

The current agent requires **configuration version 6**. Commands that read the configuration fail against a config below version 6 with an error like:

```
[error] Config version 0 is not supported (minimum: 6). Run the `slabapcli setup migrate` command to migrate your config.
```

The following commands do not check the configuration version, so you can still run them: `setup install`, `setup migrate`, `setup uninstall`, `setup upgrade`, `server start`, `server stop`, and `server uninstall`.

The migration automatically applies all necessary steps to bring the configuration to version 6.

Follow the steps below to migrate your configuration before continuing with the agent setup.

{% hint style="warning" %}
**Before you migrate:** Back up your `config\config.toml` file. The migration modifies the file in place and cannot be undone automatically.
{% endhint %}

## Run the migration

{% hint style="warning" %}
**End and disable all SeaLights scheduled tasks** in the Windows Task Scheduler before running the migration. The migration will warn you to do this — make sure they are stopped before you confirm.
{% endhint %}

Run the following from your terminal:

{% tabs %}
{% tab title="Command Prompt" %}
{% code title="Command" overflow="wrap" %}

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

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code title="Command" overflow="wrap" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

Use the `--yes` / `-y` flag to skip the interactive confirmation prompt:

{% tabs %}
{% tab title="Command Prompt" %}
{% code title="Command" overflow="wrap" %}

```batch
slabapcli.exe setup migrate --yes
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}
{% code title="Command" overflow="wrap" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

{% code title="Expected output (PowerShell)" overflow="wrap" lineNumbers="true" %}

```log
.\slabapcli.exe setup migrate
[2026-03-08 13:43:42.193+02:00] [info] Detected Windows version: Windows 11
[2026-03-08 13:43:42.195+02:00] [info] Config pathname: C:\ProgramData\Tricentis\SeaLights\ABAP Agent\config\config.toml
[2026-03-08 13:43:42.205+02:00] [info] Config version 0 detected. Migration to version 6 is required.
[2026-03-08 13:43:42.205+02:00] [warning] Please make sure to End and then Disable all Sealights scheduled tasks in the Windows Task Scheduler.
Continue? [Y/n]
```

{% endcode %}

* Enter `Y` (or press **Enter**) to proceed with the migration.
* Enter anything else, such as `n` (or `yes`), to cancel. The config file will not be changed.

When you confirm, the migration runs and writes the updated file:

{% code title="Expected output — continued (PowerShell)" overflow="wrap" lineNumbers="true" %}

```log
[info] Starting config migration from version 0 to 6
[info] Applying v0 -> v1 migration: setting version and populating pipeline appname fields
[info]   pipeline 'ERP_QAS': set appname = 'ERP_QAS'
[info]   pipeline 'ERP_QAS': set labid = 'S21 sapqas.customer.com'
[info] Applying v1 -> v2 migration: adding mandatory v2 config defaults
[info]   footprints: set typequeries from v2 defaults
[info]   componentstoignore: set components from v2 defaults
[info] Applying v2 -> v3 migration: adding [server] and [adapters] defaults from template
[info]   server: added from v3 defaults
[info]   adapters: added from v3 defaults
[info] Applying v3 -> v4 migration: adding cachedprdrfc to [[rfc]] entries
[info]   rfc 'S21': set cachedprdrfc = ''
[info] Applying v4 -> v5 migration: adding useaddon to [[pipeline]] entries
[info]   pipeline 'ERP_QAS': set useaddon = false
[info] Applying v5 -> v6 migration: raising unlimited server.uploadRetry.maxAttempts to the new default
[info]   server.uploadRetry: raised maxAttempts from 0 (unlimited) to 2
[info] Config successfully migrated to version 6.
[info] Config migrated and written to 'C:\ProgramData\Tricentis\SeaLights\ABAP Agent\config\config.toml'
```

{% endcode %}

The indented lines under each step depend on what your configuration contains. A step that finds nothing to change only updates the version number.

## What the migration does

The migration applies the following steps in sequence. If your config is already at an intermediate version, only the remaining steps are applied.

These steps describe **schema evolution within ABAP Agent 2.0 configuration**, not a product upgrade from ABAP Agent 1.3.

### v0 to v1

| Change              | Details                                                                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sets config version | Adds `version = 1` to the root of `config.toml`                                                                                                                                            |
| Backfills `appname` | Populates the `appname` field for each existing pipeline, derived from the legacy pipeline name                                                                                            |
| Backfills `labid`   | Populates any missing `labid` fields. To do this, the migration connects to each pipeline's QAS system over RFC, so that RFC destination must be configured and reachable when you migrate |

### v1 to v2

| Change                      | Details                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Sets config version         | Updates `version` to `2`                                                                                                |
| Adds `typequeries`          | Adds the default `typequeries` list to the `[footprints]` section if not already present                                |
| Adds `[componentstoignore]` | Adds the default `[componentstoignore]` section (`SAP_BASIS`, `SAP_UI`, `SAP_GWFND`, `PERSONAS`) if not already present |

### v2 to v3

| Change              | Details                                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sets config version | Updates `version` to `3`                                                                                                                                                        |
| Adds `[server]`     | Adds the default `[server]` section (HTTP server, port 5000). New installations use port 17500; a migrated configuration keeps port 5000 unless you change `port` in `[server]` |
| Adds `[adapters]`   | Adds the default `[adapters]` section for test-repository adapter configuration                                                                                                 |

### v3 to v4

| Change              | Details                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------- |
| Sets config version | Updates `version` to `4`                                                                |
| Adds `cachedprdrfc` | Adds the `cachedprdrfc` field to each `[[rfc]]` entry to support production RFC caching |

### v4 to v5

| Change              | Details                                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sets config version | Updates `version` to `5`                                                                                                                                                            |
| Adds `useaddon`     | Adds `useaddon = false` to each `[[pipeline]]` entry. See [Configuration settings — Production usage data source](broken://pages/DZM4uWEu5r51kMDWCmDB#production-usage-data-source) |

### v5 to v6

| Change               | Details                                                                                                                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sets config version  | Updates `version` to `6`                                                                                                                                                                                                                                                              |
| Raises `maxAttempts` | If `[server.uploadRetry]` sets `maxAttempts = 0` (unlimited upload retries), changes it to `2`, the new default. Other values, and configurations that do not set the key, are left unchanged. See [Configuration settings — server.uploadRetry](broken://pages/DZM4uWEu5r51kMDWCmDB) |

## Re-enable scheduled tasks

After migration, re-enable your scheduled tasks in the Windows Task Scheduler.

{% hint style="info" %}
When you upgrade with the installer, you do not need to re-enable tasks yourself. On an upgrade, the installer runs `slabapcli setup upgrade` automatically, which restores the service and each scheduled task to the state they were in before the upgrade.
{% endhint %}

## After migration

If you run `setup migrate` on a config that is already at the current version, the command exits safely with no changes:

```
[info] Config already at version 6.
```

{% hint style="info" %}
The installer runs `slabapcli setup migrate --yes` automatically during installation and upgrades of ABAP Agent 2.0 and later, and also runs `slabapcli setup upgrade` when it is upgrading an existing installation. Manual migration is only needed if you are upgrading 2.0 binaries without using the installer.
{% endhint %}