Troubleshooting Sign in with Vercel

When users try to authorize your app, several errors can occur. Common troubleshooting steps include:

• Checking that all required parameters are included in your requests
• Verifying your app configuration in the dashboard
• Reviewing the Authorization Server API documentation
• Checking the Getting Started guide for implementation examples

Vercel handles authorization errors in two ways:

• Error page: Shown when critical parameters are missing or invalid
• Redirect with error: User redirected to your callback URL with error parameters

When errors redirect to your callback URL, your application must handle them and show users an appropriate message.

These errors occur when users navigate to the authorization endpoint with invalid parameters.

When the client_id parameter is missing or references a non-existent app, Vercel shows an error page.

Fix: Verify your client_id matches the ID shown in your app's Manage page.

When the redirect_uri parameter is missing or doesn't match a registered callback URL, Vercel shows an error page.

Fix: Add the redirect URL to your app's Authorization Callback URLs in the Manage page.

When the response_type parameter is missing, Vercel redirects to your callback URL with an error:

https://example.com/api/auth/callback?
  error=invalid_request&
  error_description=Parameter 'response_type'. Required

Fix: Include response_type=code in your authorization request.

When the response_type parameter has an invalid value, Vercel redirects to your callback URL with an error:

https://example.com/api/auth/callback?
  error=invalid_request&
  error_description=Parameter 'response_type'. Invalid enum value. Expected 'code', received 'test'

Fix: Set response_type=code. This is the only supported value.

When the code_challenge parameter is provided but not between 43 and 128 characters, Vercel redirects to your callback URL with an error:

https://example.com/api/auth/callback?
  error=invalid_request&
  error_description=Parameter 'code_challenge'. code_challenge must be at least 43 characters

Fix: Generate a code_challenge that's between 43 and 128 characters long. Follow the PKCE specification for proper implementation.

When the code_challenge_method parameter has an invalid value, Vercel redirects to your callback URL with an error:

https://example.com/api/auth/callback?
  error=invalid_request&
  error_description=Parameter 'code_challenge_method'. Invalid enum value. Expected 'S256', received 'test'

Fix: Set code_challenge_method=S256. This is the only supported value.

When the prompt parameter has an invalid value, Vercel redirects to your callback URL with an error:

https://example.com/api/auth/callback?
  error=invalid_request&
  error_description=Parameter 'prompt'. Invalid enum value. Expected 'consent' | 'login', received 'test'

Fix: Use only consent or login for the prompt parameter. Leave it out if you don't need to control the authorization behavior.

When an app allows only members of its owning team to sign in, Vercel denies authorization for other accounts. Depending on the authorization flow, Vercel either shows an access denied page or redirects to your callback URL with an access_denied error and the original state value.

Fix: Sign in with a Vercel account that belongs to the app's owning team, or change the app's Sign-In Access setting to Anyone with a Vercel account. Your callback handler should also handle the standard OAuth access_denied error.

These errors occur when you call the token or revoke endpoint with an invalid OIDC token or JWT client assertion.

When you authenticate with private_key_jwt without a kid header and the JWKS has more than one matching key, Vercel returns an invalid client error.

Fix: Set kid to the key ID of the public key you signed with. client_secret_jwt does not require kid. Vercel verifies the HMAC signature against each active client secret.

When the aud claim does not match https://api.vercel.com/login/oauth/token, Vercel rejects the assertion.

Fix: Set aud to https://api.vercel.com/login/oauth/token, the token endpoint from OpenID discovery.

When you reuse a jti value, Vercel rejects the request as a replay.

Fix: Generate a unique jti for every token or revoke request.

When Vercel cannot fetch your JWKS URL, client authentication with private_key_jwt fails.

Fix: Verify the JWKS URL is publicly reachable over HTTPS. Vercel times out JWKS fetches after about 5 seconds.

When your JWKS document exceeds 64 KB, Vercel cannot load it.

Fix: Reduce the JWKS document size. The limit is 64 KB.

When Vercel cannot find a JWKS key for the assertion, verification fails.

Fix: Publish the signing public key at your JWKS URL. If the JWKS has more than one key, set kid in the assertion header to that key's ID.

When your JWKS contains more than 32 keys, Vercel cannot load it.

Fix: Keep the JWKS to 32 keys or fewer.

When client_assertion_type is not an allowed value, Vercel returns an invalid_client error with the description:

Invalid request: `client_assertion_type` should be equal to one of the allowed values "urn:ietf:params:oauth:client-assertion-type:jwt-bearer, urn:vercel:params:oauth:client-assertion-type:oidc-bearer".

Fix: Set client_assertion_type to urn:ietf:params:oauth:client-assertion-type:jwt-bearer for a JWT assertion, or urn:vercel:params:oauth:client-assertion-type:oidc-bearer for an OIDC token.

When the token's iss claim does not exactly match the issuer URL of any configured trusted issuer, or the app has no issuers configured, Vercel rejects the request with an invalid client credentials error.

Fix: Add the issuer in the dashboard. The issuer URL must match the token's iss claim exactly.

When the token's claims do not satisfy any configured entry for that issuer, Vercel rejects the request.

Fix: Compare the token's actual claims against the configured entry. To express alternatives, add another entry for the same issuer.

Unless a matching issuer entry configures an aud claim, the token's aud must be https://api.vercel.com/login/oauth/token.

Fix: Request a token with that audience from your issuer, or add aud with the token's audience to the matching issuer entry's claims.

The token's exp must be in the future, the token must include iss, sub, aud, and exp, and its signature must verify against keys from the issuer's OpenID configuration (jwks_uri). Vercel discovers the issuer's keys from its OpenID configuration, so the issuer's discovery document and JWKS must be publicly reachable.

Fix: Send a fresh token, and confirm the issuer publishes its OpenID configuration and JWKS.