Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Account Select v2 migration guide
  • Link Token migration guide
  • Legacy public key integrations
Optimizing Link
  • Optimizing Link conversion
  • Measuring Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to inititalize products
  • Returning user experience
  • Modular Link (UK/EU only)
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

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 Updating an Item.

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

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.

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 via an OAuth flow but did not grant your app permission to all of their accounts.
  • The user linked their account via an OAuth flow but did not grant your app permission to any new accounts.
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" or "Something went wrong" 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) or "Something went wrong".

Common causes
  • The full list of OAuth prerequisites have not been completed to enable your client id for a given institution's OAuth connection.
Troubleshooting steps

See the troubleshooting guide for the UNAUTHORIZED_INSTITUTION error.

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.

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.
  • The redirect URI or Android package name was not allowlisted on the Plaid Dashboard.
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.
  • An incorrect android_package_name was specified in the call to /link/token/create.
iOS
  • Universal Links are not correctly configured.
Troubleshooting steps
Android
iOS
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord