Link errors and troubleshooting

Any errors during Link will be returned via the Link flow; for details, see the guide for your specific platform. Since any failed user attempt to log on to a financial institution for any reason, even an incorrect password, will result in a Link error, you should expect to see the occasional error during Link. In most cases, Link will guide your user through the steps required to resolve the error.

The most common case in which you will need a special flow for Link errors is the ITEM_LOGIN_REQUIRED error. For instructions on handling this error, see Update mode.

For more details, or if you need to troubleshoot a problem involving an error message from the API, see Item errors.

• Your user cannot find their financial institution in Link, even though it is one of the 11,500+ institutions supported by Plaid.
• Your user experiences a "Connectivity not supported" error message after selecting their institution in Link.

• The institution does not support one of the products specified in Link initialization.
• The institution is associated with a country not specified in Link initialization.
• The institution is associated with a country your Plaid account hasn't been enabled for.

When a user tries to connect their account, they receive a message in Link that Plaid may be experiencing connectivity issues to that institution. For more details, see Institution status in Link.

• Plaid's connection to the institution is down or degraded.

Your user has multiple Items that seem to represent the same underlying set of accounts.

• The user added the same Item more than once.

Some of the end users' accounts are not present in the Item, or a new account added by the user does not appear in the Item.

• The user linked their account but did not grant your app permission to access the account, or created the account after linking the Item and did not grant your app permission to access newly created accounts.
• The account is not compatible with settings specified during the /link/token/create call. For example, if auth was one of the required products specified when calling /link/token/create, accounts that do not support Auth, such as credit card accounts, will not appear on the Item.

The Link flow is not working correctly for the user -- the onSuccess callback may not be sent, Link may not load, or redirects may not function correctly.

• Third party software, such as ad-blocking browser extensions, may be interfering with Link.
• The end user linked their account via an OAuth flow and OAuth is not configured correctly.

After selecting a bank in Link, the user gets an error message saying "You may need to update your app in order to connect to Chase" (or another institution), "Couldn't connect to your institution", or "Something went wrong". This happens only in Production.

• You haven't selected a use case for Link.
• The full list of OAuth prerequisites have not been completed to enable your client id for a given institution's OAuth connection.

When linking an Interactive Brokers account, the end user is prompted to enter a "token" and/or "query id" but does not know where or how to get one.

This is part of the standard Interactive Brokers Link flow. Interactive Brokers requires this step for any customer linking a third party service, such as Plaid, to their account.

Troubleshooting steps

First, verify these settings before reviewing the more detailed OAuth troubleshooting guides below:

If none of the steps above resolve your problem, see the specific OAuth troubleshooting guides below. If you do not see your problem listed, or following the guide does not fix the problem, contact Support.

Institutions that use OAuth, such as Capital One or Wells Fargo, are not appearing in the Link UI.

• A redirect_uri or android_package_name was not specified in the call to /link/token/create.
• The redirect URI or Android package name was not allowlisted on the Plaid Dashboard.

Upon entering their institution's OAuth flow, users see a warning that their browser is not supported.

• The Plaid integration is using a webview with an incorrectly configured user agent.

Users are not being redirected back to Link after completing their institution's OAuth flow.

Android

• An android_package_name was not specified in the call to /link/token/create.
• An incorrect android_package_name was specified in the call to /link/token/create.

iOS

• Universal Links are not correctly configured.

Android

iOS

• Link displays a "Current version not supported" message on launch, or you see a PUBLIC_KEY_NOT_ENABLED error on the backend.

• The integration is using a public key to launch Link instead of a Link token. As of February 2025, public key integrations are no longer allowed.