Skip to main content
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 installed, use powersync status to check instance status without calling the API directly. This works with any running PowerSync instance, whether local or remote.

Diagnostics API

Configuration

  1. Specify an API token in your PowerSync YAML file:
service.yaml
Use a secure, randomly generated API token.
  1. Restart the PowerSync Service.
  2. Send a POST request to the diagnostics endpoint, passing the token as a Bearer token:

Response Structure

The response data object contains: service: information about the running PowerSync Service. service.version is the Service version, such as 1.27.1. connections — whether PowerSync can reach the configured source database and any connection-level errors. active_sync_rules — the currently serving Sync Config. 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: the next Sync Config submitted for deployment. If valid, the Service runs its initial replication while any existing active config continues serving clients. Once initial replication completes, this section disappears and active_sync_rules updates. A configured Sync Config with fatal validation errors appears here without being processed. See Errors and Warnings for details. sync_config_source: where the Service gets its Sync Config. The value is config if the Sync Config is defined in the Service configuration, such as the sync_config: section of service.yaml. Otherwise, the value is api, and the Sync Config is deployed via the API. Each connection in active_sync_rules.connections[] includes:

Errors and Warnings

Since Service version 1.28.0, the Service rejects configured Sync Configs with fatal parsing or validation errors before writing them to bucket storage. Validation includes checks that the source supports the features the config uses. This applies to configs supplied through a file, inline content, or a Base64 environment variable. With sync_config.exit_on_error: false, the errors appear in deploying_sync_rules.errors[] even though the rejected config is not replicated or served to clients. Any previous active config continues replicating and serving clients. Correct the configured Sync Config and restart the affected Service processes to reload and validate it. If you run separate API and replication processes, supply the same corrected config to both and restart both. Warnings and errors appear in the errors[] array at the Sync Config 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).
For guidance on configuring max_slot_wal_keep_size and managing replication slots, see Postgres maintenance.