> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics

> How to use the PowerSync Service Diagnostics API to inspect replication status, errors, and slot health.

All self-hosted PowerSync Service instances ship with a Diagnostics API for inspecting replication state, surfacing errors, and monitoring source database health.

## CLI

If you have the [PowerSync CLI](/tools/cli) installed, use `powersync status` to check instance status without calling the API directly. This works with any running PowerSync instance, whether local or remote.

```bash theme={null}
powersync status

# Extract a specific field
powersync status --output=json | jq '.data.active_sync_rules'
```

## Diagnostics API

### Configuration

1. Specify an API token in your PowerSync YAML file:

```yaml service.yaml theme={null}
api:
  tokens:
    - YOUR_API_TOKEN
```

<Warning>Use a secure, randomly generated API token.</Warning>

2. Restart the PowerSync Service.

3. Send a POST request to the diagnostics endpoint, passing the token as a Bearer token:

```shell theme={null}
curl -X POST http://localhost:8080/api/admin/v1/diagnostics \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### Response Structure

The response `data` object contains:

**`connections`** — whether PowerSync can reach the configured source database and any connection-level errors.

**`active_sync_rules`** — the currently serving sync config (Sync Streams or Sync Rules). Contains a `connections[]` array with details about each replication connection including slot name, WAL status, and tables being replicated. Also includes an `errors[]` array for warnings or errors.

**`deploying_sync_rules`** — only present while a new sync config is being deployed and the initial replication is in progress. PowerSync runs this process in parallel so clients continue to be served by the existing active config. Once initial replication completes, this section disappears and `active_sync_rules` updates.

Each connection in `active_sync_rules.connections[]` includes:

| Field                      | Description                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `slot_name`                | The name of the Postgres replication slot used by this Sync Rules version.                |
| `initial_replication_done` | Whether the initial snapshot has completed.                                               |
| `replication_lag_bytes`    | Replication lag in bytes.                                                                 |
| `wal_status`               | The WAL status of the replication slot (`reserved`, `extended`, `unreserved`, or `lost`). |
| `safe_wal_size`            | Remaining WAL budget in bytes before the slot risks invalidation.                         |
| `max_slot_wal_keep_size`   | The configured `max_slot_wal_keep_size` value on the source Postgres database.            |

### Errors and Warnings

Warnings and errors appear in the `errors[]` array at the Sync Rules level (`active_sync_rules.errors[]` or `deploying_sync_rules.errors[]`). This includes:

* **Replication lag warnings** are raised if no replicated commit has been received in more than 5 minutes (warning level) or 15 minutes (fatal level).
* **WAL budget warnings** appear when the remaining WAL budget drops below 50%.
* **Replication errors** such as `PSYNC_S1146` appear when a replication slot is invalidated (when `wal_status` is `lost`).

<Tip>
  For guidance on configuring `max_slot_wal_keep_size` and managing replication slots, see [Postgres maintenance](/configuration/source-db/postgres-maintenance).
</Tip>