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

# Troubleshooting

> Diagnose Connect.js setup, open, callback, reauthorization, and token-exchange failures.

Start with the observed symptom, then check the earliest lifecycle step that could produce it.

## The widget does not open

Check these conditions in order:

1. The code is running in a browser with `window` and `document` available.
2. `new Connect(...)` completed without throwing.
3. `setup()` or `reauthorise(accountId)` ran before `open()`.
4. `open()` runs from a user action such as a button click.
5. Browser policy, an extension, or a Content Security Policy is not blocking `https://connect.mono.co`.

In Next.js, initialize the SDK in a Client Component. Do not mount the widget during server rendering.

## Constructor errors

The current SDK throws synchronously when either required constructor value is missing.

| Error                            | Cause                        | Fix                                                                                |
| -------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------- |
| `PUBLIC_KEY is required`         | `key` is empty or undefined. | Load the Mono public key in browser-safe configuration.                            |
| `onSuccess callback is required` | `onSuccess` was omitted.     | Pass a function even if the first implementation only logs or forwards the result. |

## Reauthorization errors

`reauthorise()` requires a Mono account ID string.

| Error                                         | Cause                                         | Fix                                              |
| --------------------------------------------- | --------------------------------------------- | ------------------------------------------------ |
| `Account ID is required for re-authorisation` | No account ID was passed.                     | Load the stored account ID for the current user. |
| `Invalid accountId: must be a string`         | A number, object, or another type was passed. | Pass the account ID string returned by Mono.     |

Do not pass the initial auth code or a value labeled `reauthToken`.

## `onSuccess` runs, but no account is stored

The browser callback returns a short-lived code. Your backend must still exchange it.

Check that:

* the browser sends `{ code }` to an authenticated backend route
* `MONO_SECRET_KEY` exists only in the server environment and is sent through `mono-sec-key`
* the backend parses the exchange response using Mono's current schema
* non-2xx responses are logged without exposing secrets
* the resulting account ID is stored against the correct application user

Use Mono's [official exchange-token reference](https://docs.mono.co/api/bank-data/authorisation/exchange-token) as the authority for the current request and response schema.

## Events appear more than once

Create one Connect instance per mounted page or component. Recreating the instance on every render can mount multiple widgets or register repeated listeners.

In React, create the instance inside `useEffect` and keep it in `useRef`. In Angular, initialize it in `ngOnInit`. In Next.js, keep initialization inside a Client Component.

## The wrong institution or account flow opens

Review the object passed to `setup()`:

```javascript theme={null}
connect.setup({
  selectedInstitution: {
    id: "INSTITUTION_ID",
    auth_method: "internet_banking",
    account_number: "ACCOUNT_NUMBER"
  },
  check_account_match: true
})
```

Remove `selectedInstitution` to return to the institution-selection screen. Confirm institution IDs and supported authentication methods against current coverage data.

## Collect a safe diagnostic record

Capture the SDK version, browser, flow type, event names, HTTP status codes, and your own correlation reference. Do not record credentials, MFA values, BVNs, account numbers, secret keys, or full event payloads that may contain sensitive data.