---
source_url: https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/connection-management
title: Connection management
updated_at: 2026-05-19T12:10:03.189Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Connection management

Handle subscription errors and restore connections when network issues occur.

## Connection status listener

Monitor connection status in real time to track subscription state and react to network or authentication errors.

### Method signature

This method takes the following parameters:

```kotlin
chat.addConnectionStatusListener(
    callback: (ConnectionStatus) -> Unit
): AutoCloseable
```

#### Input

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| callback | (ConnectionStatus) | Yes |  | Function invoked on every connection status change with a [ConnectionStatus](#connectionstatus) object. |

#### Output

| Type | Description |
| --- | --- |
| `AutoCloseable` | A handle you can call `close()` on to remove the listener. |

:::note Remove the listener
Call `close()` on the returned `AutoCloseable` to remove the listener.
:::

### Connection status types

The connection status listener reports the following status types:

| Status | Description |
| --- | --- |
| `PN_CONNECTION_ONLINE` | The connection has been established and is ready to receive real-time updates. |
| `PN_CONNECTION_OFFLINE` | The connection has been intentionally terminated. |
| `PN_CONNECTION_ERROR` | The connection was unexpectedly lost or failed to establish. Contains error details. |

### ConnectionStatus

| Property | Description |
| --- | --- |
| `category` *Type: `ConnectionStatusCategory` | Current connection status category. See [Connection status types](#connection-status-types). |
| `exception`Type: `PubNubException?` | Error details when `category` is `PN_CONNECTION_ERROR`; `null` otherwise. |

### Sample code

Set up a connection status listener to monitor your chat connection and automatically reconnect on errors.

```kotlin
val statusListener = chat.addConnectionStatusListener { status: ConnectionStatus ->
    when (status.category) {
        ConnectionStatusCategory.PN_CONNECTION_ONLINE -> {
            println("Received status PN_CONNECTION_ONLINE")
        }
        ConnectionStatusCategory.PN_CONNECTION_OFFLINE -> {
            println("Received status PN_CONNECTION_OFFLINE")
        }
        ConnectionStatusCategory.PN_CONNECTION_ERROR -> {
            println("Received status PN_CONNECTION_ERROR with error: ${status.exception?.message}")
            // Attempt to recover all subscriptions
            chat.reconnectSubscriptions().async { result ->
                result.onSuccess {
                    println("Reconnected subscriptions")
                }.onFailure { ex ->
                    println("Reconnect failed: ${ex.message}")
                }
            }
        }
    }
    Unit
}

// Remove connection status listener
statusListener.close()
```

## Reconnect subscriptions

Restore previous subscriptions with all subscribed channels and listeners. Call after `disconnectSubscriptions()` or when receiving `PN_CONNECTION_ERROR`.

### Method signature

```kotlin
chat.reconnectSubscriptions(): PNFuture<Unit>
```

#### Output

| Type | Description |
| --- | --- |
| `PNFuture<Unit>` | A future that completes on success or fails with a `PubNubException`. |

### Sample code

Reconnect all subscriptions after a connection error.

```kotlin
chat.reconnectSubscriptions().async { result ->
    result.onSuccess {
        // handle success
    }.onFailure {
        // handle failure
    }
}
```

## Disconnect subscriptions

Pause all active subscriptions and listeners.

### Method signature

```kotlin
chat.disconnectSubscriptions(): PNFuture<Unit>
```

#### Output

| Type | Description |
| --- | --- |
| `PNFuture<Unit>` | A future that completes on success or fails with a `PubNubException`. |

### Sample code

Disconnect all subscriptions when you want to pause real-time updates.

```kotlin
chat.disconnectSubscriptions().async { result ->
    result.onSuccess {
        // handle success
    }.onFailure {
        // handle failure
    }
}
```

## Troubleshooting

Recommended workflow for handling subscription errors:

1. Initialize monitoring: Add the connection status listener immediately after creating the Chat instance.
2. Handle errors: On PN_CONNECTION_ERROR, call reconnectSubscriptions().
3. Manual control: Call disconnectSubscriptions() when pausing real-time updates (for example, when the app backgrounds).
4. Restore connection: Call reconnectSubscriptions() to resume.

This pattern maintains stable connectivity and automatic recovery from network issues.