> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Handle SanityLive connection events

Turn off or replace the default SanityLive event handlers in next-sanity, and learn when an "attempting to reconnect" console error needs attention.

The `<SanityLive>` component that `defineLive` returns keeps a connection open to the [Live Content API](https://www.sanity.io/docs/content-lake/live-content-api) and reacts to the events it receives. Each connection event has a default handler: some log to the browser console, and others refresh the route.

This guide shows how to turn off the default handlers, replace them with your own, and decide when a reconnect message needs attention.

Prerequisites:

- next-sanity v13 or later in a Next.js App Router project. Earlier versions don't have the `onWelcome`, `onReconnect`, and `onRestart` props, and `onGoAway` has a different signature.
- `<SanityLive>` set up with `defineLive`. See [Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide).

## Default behavior of each event handler

`<SanityLive>` accepts one prop per connection event. When you leave a prop unset, its default handler runs:

- `onWelcome`: runs when the connection is established. Logs a `console.info` message such as `<SanityLive> is connected and listening for live events to published content.`.
- `onReconnect`: runs when the connection drops and a reconnect attempt is scheduled. Logs `<SanityLive> is attempting to reconnect` with `console.error`.
- `onRestart`: runs when the Live Content API restarts the event stream. Calls `router.refresh()` so Server Components render with fresh data.
- `onGoAway`: runs when the API closes the connection and won't deliver live events, for example when connection limits are reached. Logs a `console.warn` message and refreshes the route every 30 seconds instead.
- `onError`: runs on connection, parsing, and event-processing errors. Logs the error with `console.error`. When the error is caused by the site's origin missing from the project's CORS origins, it logs a `console.warn` message with a link to add the origin.

When `<SanityLive>` includes drafts, the default connection, reconnect, and `goaway` messages start with `<SanityLive includeDrafts>` instead.

## Decide whether a reconnect needs attention

The default `onReconnect` handler logs with `console.error`, so `<SanityLive> is attempting to reconnect` appears as an error in the browser console. On its own, it doesn't mean live updates are broken.

A reconnect happens when the connection drops for a reason that's expected to be temporary: a network interruption, a server error (`5xx`), a request timeout (`408`), or rate limiting (`429`). The client reconnects automatically. A successful reconnect fires the `welcome` event again, so with the default handlers the connected message follows the reconnect message.

If the server rejects the connection with any other `4xx` status, such as for an expired or invalid token, the client doesn't reconnect. The error goes to `onError` instead.

Investigate when reconnect messages repeat with no connected message in between, or when `onError` reports errors. To keep routine reconnects out of the error log, turn off `onReconnect` or replace it with a handler that logs a warning.

## Turn off default handlers

Pass `false` to a handler prop to turn off its default behavior. This example turns off the connection and reconnect logs:

**src/app/layout.tsx**

```tsx
import {SanityLive} from '@/sanity/lib/live'

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        {children}
        <SanityLive onWelcome={false} onReconnect={false} />
      </body>
    </html>
  )
}
```

Turning off `onRestart` or `onGoAway` changes more than logging:

- `onRestart={false}`: the route no longer refreshes when the Live Content API restarts the event stream.
- `onGoAway={false}`: there's no fallback polling. When the API closes the connection, `<SanityLive>` passes the error `Sanity Live connection closed, automatic revalidation is disabled, the server gave this reason: REASON` to `onError`, and content stops updating.

`onError` doesn't accept `false`. To change how errors are handled, replace it with your own handler.

## Replace a default handler

`<SanityLive>` from `defineLive` renders as a Server Component and passes your handlers to a Client Component. Define your handlers in a module marked with `'use client'` so they run in the browser, then import them into your layout.

This example logs reconnects as warnings and, when the API closes the connection, refreshes the route once a minute instead of every 30 seconds:

**src/app/sanity-live-handlers.ts**

```typescript
'use client'

import type {SanityLiveOnGoaway, SanityLiveOnReconnect} from 'next-sanity/live'

export const onReconnect: SanityLiveOnReconnect = (_event, {includeDrafts}) => {
  console.warn(`<SanityLive${includeDrafts ? ' includeDrafts' : ''}> lost its connection and is reconnecting`)
}

export const onGoAway: SanityLiveOnGoaway = (event, _context, setPollingInterval) => {
  console.warn('Sanity Live connection closed:', event.reason)
  setPollingInterval(60_000)
}
```

**src/app/layout.tsx**

```tsx
import {SanityLive} from '@/sanity/lib/live'
import {onGoAway, onReconnect} from './sanity-live-handlers'

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en">
      <body>
        {children}
        <SanityLive onReconnect={onReconnect} onGoAway={onGoAway} />
      </body>
    </html>
  )
}
```

Each handler receives the event and a context object. The context has `includeDrafts` and `waitFor`, which describe the current connection. Import the handler types from `next-sanity/live`:

- `onWelcome`: `SanityLiveOnWelcome`.
- `onReconnect`: `SanityLiveOnReconnect`.
- `onRestart`: `SanityLiveOnRestart`. Return `'refresh'` from your handler to also refresh the route. Passing the string `'refresh'` instead of a function is the default behavior.
- `onGoAway`: `SanityLiveOnGoaway`. Receives a third argument, `setPollingInterval(ms)`, which refreshes the route on that interval. If your handler doesn't call it, content stops updating after the connection closes.
- `onError`: `SanityLiveOnError`. Receives the error and the context. Pass the string `'throw'` instead of a function to throw the error during render, so the nearest error boundary handles it.

## Next steps

- [Add live content to your application](https://www.sanity.io/docs/developer-guides/live-content-guide): set up `defineLive` and `<SanityLive>`.
- [Sanity Live with Next.js Cache Components](https://www.sanity.io/docs/nextjs/cache-components): configure `<SanityLive>` for `cacheComponents: true`.
- [Live Content API](https://www.sanity.io/docs/content-lake/live-content-api): how the event stream works.