Link (2024)

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.

• 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.

Make sure not to initialize Link with any products your application isn't using.

Make sure Link is initialized for the country in which the institution operates.

If the problem occurs in Production but not in Sandbox or Developmentenvironments, your Plaid developer account may not have been enabled for thecountry in which the institution operates. Submit a product accessrequestvia the Plaid Dashboard to gain access.

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.

If your user cannot link their account, ask them to try again later.

If possible, provide a manual, backup flow for the user to enter account information.

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.

Prompt the user to enter the update mode flow, which will allow them to change the permissions they have granted to your app.

Ensure that the /link/token/create call is configured in a way that is compatible with all the desired accounts.

If accounts disappeared after the Item was linked, see the Troubleshooting guide for INVALID_ACCOUNT_ID.

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.

Ask the end user to temporarily disable ad-blockers or other third-party browser extensions that may be interfering with Link and try again.

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".

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

See the troubleshooting guide for the UNAUTHORIZED_INSTITUTION error.

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:

Ensure your redirect URI is configured in the Plaid Dashboard

For web, iOS SDK, or React Native iOS integrations, ensure the redirect_uri parameter is set in the /link/token/create call for all Link sessions, including Link in update mode.

For Android SDK integrations, ensure that your Android package name is registered in the Plaid Dashboard and that the android_package_name parameter is set in the /link/token/create call for all Link sessions, including Link in update mode.

For iOS SDK integrations, check that the redirect URI has been associated with an Apple App Association file and that your application has the associated-domains entitlement for that URI. For more details, see the OAuth guide.

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.

Make sure the redirect_uri (or, for Android, android_package_name) is specified in the call to /link/token/create.

Make sure to list your redirect URI or Android package name in the Plaid Dashboard. This setting can be found under Team settings -> API -> Allowed redirect URIs (or Allowed Android package names) -> Configure.

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.

Use an official Plaid mobile SDK rather than a webview-based integration. Mobile SDK integrations are strongly recommended over the use of webviews.

Ensure that the webview uses a valid user agent matching one commonly found in the wild.

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

Make sure the android_package_name is correctly specified in the call to /link/token/create.

iOS

Ensure you are testing on a physical device and not an iOS simulator. Universal Links may not always work correctly on the simulator.

Visit your redirect URI manually and confirm that it opens your app. You can do this by either clicking on this URI in a link (for instance, by adding it to the Reminders app) or by using the command line tool to open the URL in your currently running simulator: xcrun simctl openurl booted '<your URI>'.

If this does successfully open your app, confirm that the redirect_uri is correctly set in your /link/token/create call. If does not, there is likely a problem with the apple-app-site-association file or the entitlements for the app; view the troubleshooting steps below.

Test the apple-app-site-association file by taking the domain (not the full path) of the redirect_uri and accessingthe corresponding location on Apple's CDN using a web browser. For example, if the redirect_uri is https://app.wonderwallet.com/plaid, then visit https://app-site-association.cdn-apple.com/a/v1/app.wonderwallet.com.

If the contents of the apple-app-site-association blob do not appear, then Apple does not have a copy of the apple-app-site-association file at the correct location needed to invoke Universal Links. See Apple's Universal Links documentation for information on how to create, name, and locate this file.

Confirm that the apple-app-site-association contains the exact and correct path for the redirect_uri.

Confirm that the apple-app-site-association is not malformatted, using a tool such as the ASAA validator. If combining iOS 12 style (paths:) and iOS 13 or higher style (components:) formats, the two should be in separate sections of the file, as in this example app site association file.