Troubleshooting

• Validator end-to-end failures — Pre-launch test failing in the Dashboard Validator
• Common OAuth errors — Connection failing during OAuth
• Common integration issues — API calls returning errors
• JWKS validation issues — Token validation failing
• Logging — Debug a specific flow or unsure where to look
• FDX Explorer — Reference OAuth flow with interactive demo

The Validator runs in the Data Partner Dashboard and exercises your discovery, OAuth, and data endpoints before production launch. End-to-end runs can fail before any OAuth traffic reaches your authorize or token endpoints — usually at the discovery step.

Issue: The Validator end-to-end test fails immediately with Error getting OIDC configuration. Please also make sure you have allowlisted Plaid IPs.

Cause: This message covers two unrelated failure modes that need different fixes:

1. The discovery URL (/.well-known/openid-configuration) is not reachable from the public internet — most often a 404, a firewall or WAF block, or a TLS/DNS error.
2. The discovery URL returns 200 but the response body is missing required fields (see Well-known configuration).

IP allowlisting configuration issues are rarely the cause at this step. Plaid fetches /.well-known/openid-configuration and jwks_uri from infrastructure outside the IP ranges in the IP allowlist documentation, so these endpoints must remain reachable from the public internet.

How to debug, in order:

1. From a network outside your firewall and any internal IP allowlist, run:

   curl -v 'https://YOUR_DOMAIN/.well-known/openid-configuration'

   Expect HTTP 200 with Content-Type: application/json. If you get 404, 403, a TLS error, or a connection timeout, the URL is not publicly reachable — fix DNS, firewall/WAF rules, or the route itself, then re-run the Validator. Confirm your firewall does not restrict this path to the Plaid IP ranges.

2. If step 1 returns 200, verify the JSON body includes authorization_endpoint, token_endpoint, response_types_supported (with code), scopes_supported (with offline_access, plus openid for OIDC), and userinfo_endpoint and jwks_uri for OIDC. Missing or misnamed fields will fail the Validator with the same generic message.

3. If steps 1 and 2 both pass, the discovery layer is healthy — the underlying failure is on token_endpoint, userinfo_endpoint, or a data endpoint, not discovery. The IP allowlist applies to those endpoints; confirm it is configured correctly there.

These are standard OAuth error codes your server should return to Plaid:

If Plaid encounters problems validating your ID tokens, connections will fail and your conversion rates will drop. These issues typically show up as authentication failures in your logs or low conversion metrics in the Data Partner Dashboard. Your Solutions Engineer may reach out to help troubleshoot.

Good logging significantly reduces debugging time. Log the following identifiers for every session:

Plaid sends the X-Request-ID header when calling your token_endpoint and resource server endpoints:

X-Request-ID: req_4h8j2k9m3n7p5q1r

Include these identifiers in support tickets to speed up resolution.

Plaid sends email notifications when integration issues are detected, with a link to the issue in your dashboard. Use the Issue Center to see all active issues at a glance, and drill into individual issue detail pages to debug using error trends, sample errors, and request-level logs.

In addition to responding to alerts, proactively monitor:

• HTTP status codes and latency for authorize, token, userinfo, and jwks_uri endpoints
• Error rates: Alert if > 2%
• OAuth and JWKS errors: Log with timestamp and state

Opening a support ticket? Include:

• state value
• Timestamp and user ID
• Error message and HTTP status
• Request/response headers (mask the secrets!)
• X-Request-ID from the request headers
• Recent log entries surrounding the error

The more context you provide, the faster the resolution.

Beyond standard OAuth errors, watch for these implementation problems:

Issue: API response validation fails because a field contains null instead of the expected data type (string, number, array, etc.).

Cause: Returning null for a field when the schema expects a typed value.

Resolution:

• Required fields: Return a value in the expected type. If data is unavailable, use an empty string ("") for strings or an empty array ([]) for arrays.
• Optional fields: Omit the field entirely from the response rather than setting it to null.

// Don't do this
{
  "email": null,
  "phoneNumbers": null
}

// Do this instead
{
  "email": "",
  "phoneNumbers": []
}

// Or this (omit optional fields)
{
  "email": ""
}

Issue: Plaid limits how many times it will call a paginated endpoint before throwing an error.

Cause: The nextOffset field (or equivalent pagination parameter) is set to null or an empty string on the final page instead of being omitted.

Resolution: On the last page of results, omit the nextOffset field completely. Don't set it to null, empty string, or 0.

Example:

// Don't do this (last page)
{
  "data": [...],
  "nextOffset": null
}

// Do this instead (last page)
{
  "data": [...]
}

Issue: Data Providers trying to debug OAuth issues don't see logs in the Data Partner Dashboard.

Cause: Plaid only provides logs after the user successfully passes initial authentication steps. If the OAuth flow fails during authorization or before the token exchange completes, logs will not be available.

Resolution: Contact Plaid support to review internal logs and identify where the flow broke. Common pre-log issues include: invalid client_id, HTTPS errors, or redirect URI mismatch.

Issue: Refresh token flow fails with invalid_grant error during background updates.

Cause: Refresh token expired before Plaid attempted to use it. This error can occur when the refresh token lifetime is set too short or when the DP revokes tokens after a period of inactivity.

Resolution:

• Set refresh token expiration to 13+ months
• Don't use inactivity timeouts on refresh tokens
• If revocation is necessary, coordinate with Plaid to avoid breaking active connections

Issue: Connection fails because the user identifier (consistency key) returned in the id_token sub field or /customers/current is fewer than seven characters.

Cause: Consistency key too short to meet minimum requirements.

Resolution: Use a longer identifier or a prefix with the institution code, with a minimum length of seven characters.

// Too short
{"sub": "12345"}

// Acceptable length
{"sub": "user_12345"}