Link errors and troubleshooting  ================================ #### Errors in the Link flow  #### Link error codes  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](https://plaid.com/docs/link/update-mode/index.html.md) . For more details, or if you need to troubleshoot a problem involving an error message from the API, see [Item errors](https://plaid.com/docs/errors/item/index.html.md) . #### Missing institutions or "Connectivity not supported" error  ##### Symptom  * 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. ##### Common causes  * 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. ##### Troubleshooting steps  #### Institution unhealthy  ##### Symptom  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](https://plaid.com/docs/link/institution-status/index.html.md) . ##### Common causes  * Plaid's connection to the institution is down or degraded. ##### Troubleshooting steps  #### Duplicate Items  ##### Symptom  Your user has multiple Items that seem to represent the same underlying set of accounts. ##### Common causes  * The user added the same Item more than once. ##### Troubleshooting steps  #### Missing accounts  ##### Symptom  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. ##### Common causes  * 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](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. For example, if `auth` was one of the required products specified when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , accounts that do not support Auth, such as credit card accounts, will not appear on the Item. ##### Troubleshooting steps  #### Link flow is failing  ##### Symptom  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. ##### Common causes  * 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. ##### Troubleshooting steps  #### "You may need to update your app", "Couldn't connect to your institution", or "Something went wrong: an internal error occurred" error message  ##### Symptom  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: an internal error occurred". ##### Common causes  * You haven't selected a use case for Link. * The full list of OAuth prerequisites has not been completed to enable your client ID for a given institution's OAuth connection. * A backend error occurred during the Link flow. ##### Troubleshooting steps  #### Interactive Brokers customer prompted to enter a query id and token  ##### Symptom  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. ##### Common causes  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  #### OAuth not working  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](https://dashboard.plaid.com/support/new/product-and-development/developer-lifecycle/sdk) . #### OAuth institutions not appearing in Link  ##### Symptom  Institutions that use OAuth, such as Capital One or Wells Fargo, are not appearing in the Link UI. ##### Common causes  * A `redirect_uri` or `android_package_name` was not specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * The redirect URI or Android package name was not allowlisted on the [Plaid Dashboard](https://dashboard.plaid.com/developers/api) . ##### Troubleshooting steps  #### OAuth flow shows unsupported browser warning  ##### Symptom  Upon entering their institution's OAuth flow, users see a warning that their browser is not supported. ##### Common causes  * The Plaid integration is using a webview with an incorrectly configured user agent. ##### Troubleshooting steps  #### OAuth redirects not working  ##### Symptom  Users are not being redirected back to Link after completing their institution's OAuth flow. ##### Common causes  ###### Android  * An `android_package_name` was not specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * An incorrect `android_package_name` was specified in the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ###### iOS  * Universal Links are not correctly configured. ##### Troubleshooting steps  ###### Android  ###### iOS  #### "Current version not supported" or PUBLIC\_KEY\_NOT\_ENABLED  ##### Symptom  * Link displays a "Current version not supported" message on launch, or you see a `PUBLIC_KEY_NOT_ENABLED` error on the backend. ##### Common causes  * 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. ##### Troubleshooting steps