Troubleshooting

Debug OAuth issues faster with proper logging and error handling

Where to start

Validator end-to-end failures

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.

Error getting OIDC configuration

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

Cause: Plaid couldn't fetch your discovery document (/.well-known/openid-configuration): the request failed or returned a status other than 200. Common causes:

  1. A firewall, WAF, or IP allowlist blocks Plaid's request. Plaid fetches the discovery document from the allowlisted IP ranges, so a rule that excludes those ranges breaks this step.
  2. The URL returns 404, or there's a TLS or DNS error.
  3. Your discovery endpoint requires mTLS, but Plaid isn't configured to present a client certificate for it.

A discovery document that returns 200 but is missing required fields doesn't produce this message; the run fails at a later step instead.

How to debug, in order:

  1. Run:

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

    Expect HTTP 200 with a JSON body. If you get 404, a TLS error, or a connection timeout, fix DNS, the route, or your TLS configuration, then re-run the Validator.

  2. Confirm that your firewall, WAF, and IP allowlist let the Plaid IP ranges reach this path, and that it doesn't require mTLS unless you've set that up with Plaid. A successful curl from your own network doesn't rule out a rule that blocks Plaid.

  3. Verify the JSON body includes authorization_endpoint, token_endpoint, response_types_supported (with code), scopes_supported (with offline_access, plus openid for OIDC), and jwks_uri for OIDC. A missing field won't cause this message, but it fails the run later.

Quick fixes

OAuth errors you should return

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

Error codeWhen to returnFix
access_deniedUser cancelled authorizationNormal user behavior - log but don't alert
invalid_grantAuthorization code expired or was reusedReduce latency, expire codes in 10 min, enforce single-use
temporarily_unavailableYour server is overloaded or in maintenanceCheck capacity, implement rate limiting, add monitoring

JWKS and token validation issues

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.

Common JWKS problems and fixes

ProblemHow you would noticeWhat to check
ID token signature validation failingConnection failures, user complaintsVerify kid in token header matches a key in your published JWKS
Key rotation issuesSudden spike in auth failures after key rotationConfirm new keys published to JWKS before removing old ones (24-hour overlap)
JWKS endpoint unreachableAll connections failing, Plaid can't validate any tokensCheck endpoint uptime, DNS resolution, firewall rules, and HTTPS configuration

Logging

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

IdentifierPurpose
stateCorrelates redirect and token exchange.
userIdYour internal authenticated user ID.
timestampISO-8601 timestamp of each request/response.
X-Request-IDPlaid request identifier sent in request headers. Correlate with the Dashboard's Integration Health view.
oauth_session_id (optional)Your unique session tracker.

Plaid sends the X-Request-ID header, a UUID that may omit its dashes, when calling your Core Exchange data endpoints:

Example request header
X-Request-ID: 0f1e4f4e6c2a4a1d9c4e2a1d0f1e4f4e

Include these identifiers in support tickets to speed up resolution.

JWKS validation issues

These issues only apply to OIDC implementations that issue ID tokens. Plain OAuth 2.0 implementations don't use JWKS.

ProblemDescriptionResolution
Invalid signatureID token signature cannot be verified.Ensure JWKS is reachable and current.
Unknown kidToken kid does not match any published key.Verify correct key rotation and header values.
JWKS unreachableJWKS endpoint not available.Confirm HTTPS accessibility and DNS resolution.

Common OAuth errors

ErrorMeaningResolution
invalid_requestMissing/invalid parameter.Validate query parameters; ensure redirect_uri and scope are present.
invalid_clientClient authentication failed.Confirm client_id/secret.
unauthorized_clientThe client is not authorized to use this grant type.Confirm the grant types enabled for Plaid's client_id.
invalid_grantCode expired or reused.Make codes one-time use; expire within < 10 min.
temporarily_unavailableDP downtime or maintenance.Retry; notify Plaid of planned maintenance.

A redirect_uri that doesn't match the value registered for Plaid's client_id has no error code, because you should not redirect at all in that case — show an error page instead. See What if the redirect_uri doesn't match?.

Monitoring and alerting

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

When you need help

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.

Common integration issues

Beyond standard OAuth errors, watch for these implementation problems:

Validation failures

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 real value of the expected type. If you can't source a required field, contact Plaid rather than sending an empty value; some required arrays, such as telephones on /accounts/{accountId}/contact, must contain at least one entry.
  • Optional fields: Omit the field entirely from the response rather than setting it to null.
Data examples
// Don't do this
{
  "nickname": null
}

// Do this instead (omit optional fields)
{}

Iteration limit exceeded

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

Cause: Your endpoint keeps returning a next-page cursor (nextOffset or nextPageKey), so Plaid never reaches a final page. A common source is a last page that still sets nextOffset, for example to 0, which Plaid treats as another page. An empty-string nextOffset fails with a different error, Invalid CoreX pageOffset pagination metadata.

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

Example:

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

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

No logs visible in Data Partner Dashboard

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.

invalid_grant during refresh

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

User identifier rejected (consistency key)

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.

User ID examples
// Too short
{"sub": "12345"}

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