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 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():

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.