n8n Troubleshooting: OAuth Token Expiration

OAuth token expiration will break your workflows. Here's how to fix it, prevent it, and build self-healing automation that handles token refreshes without manual intervention.

OAuth tokens fail in two ways: silently (the workflow runs but produces no results) or loudly (execution errors). You need to catch both.

Check Execution Errors

Open your workflow execution history. Failed nodes show a red indicator. Click the node to view the error details.

Common error messages by service:

Google Workspace (Sheets, Drive, Gmail)

Error: invalid_grant: Token has been expired or revoked
Error: Request had invalid authentication credentials

Microsoft 365 (Outlook, OneDrive, Teams)

Error: InvalidAuthenticationToken
Error: CompactToken parsing failed with error code: 80049217

Slack

Error: invalid_auth
Error: token_revoked

Salesforce

Error: INVALID_SESSION_ID
Error: Session expired or invalid

Check Credential Status in n8n

Navigate to Credentials in the left sidebar. Credentials with expired tokens show a warning icon. Click any credential to view its status.

For OAuth2 credentials, n8n displays:

• Last connection date
• Token refresh status
• Whether auto-refresh is enabled

If you see "Connection failed" or "Needs reconnection," the token is dead.

Monitor Workflow Execution Patterns

Token expiration often appears as a sudden pattern change. A workflow that ran successfully for weeks suddenly fails at the same node every time. Check the execution timeline - if all failures started on the same day, suspect token expiration.

n8n handles token refresh automatically for most OAuth2 services, but only if the refresh token itself hasn't expired. Here's how to force a manual refresh when auto-refresh fails.

Manual Token Refresh (Standard OAuth2)

Step 1: Open the workflow containing the failed node.

Step 2: Click the node, then click the credential name in the node parameters.

Step 3: In the credential modal, click Reconnect Account or Reauthorize.

Step 4: Complete the OAuth flow in the popup window. Grant all requested permissions.

Step 5: Return to n8n. The credential modal should show "Connected" with a green checkmark.

Step 6: Click Save on the credential, then Save on the workflow.

Step 7: Execute the workflow manually to verify the connection works.

Manual Token Refresh (Google OAuth2)

Google tokens require special handling because Google's refresh tokens can expire if unused for 6 months.

Step 1: Go to Credentials and locate your Google OAuth2 credential.

Step 2: Click Delete (yes, delete it - you'll recreate it).

Step 3: Create a new credential. Select Google OAuth2 API as the credential type.

Step 4: Enter your OAuth Client ID and Client Secret. If you don't have these:

• Go to Google Cloud Console
• Select your project (or create one)
• Navigate to APIs

  APIs

  Click to read the full definition in our AI & Automation Glossary.

  & Services > Credentials
• Click Create Credentials > OAuth 2.0 Client ID
• Set application type to Web application
• Add https://your-n8n-instance.com/rest/oauth2-credential/callback to Authorized redirect URIs
• Copy the Client ID and Client Secret

Step 5: In n8n, add the required scopes. For Google Sheets:

https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.file

Step 6: Click Connect my account and complete the OAuth flow.

Step 7: Update all nodes using the old credential to use the new one.

Manual Token Refresh (Microsoft OAuth2)

Microsoft tokens expire after 90 days of inactivity. The refresh process is similar but requires tenant-specific configuration.

Step 1: Verify your Azure AD app registration includes the correct redirect URI: https://your-n8n-instance.com/rest/oauth2-credential/callback

Step 2: In n8n, open the Microsoft OAuth2 credential.

Step 3: Verify these fields match your Azure AD app:

• Client ID (Application ID from Azure)
• Client Secret (from Certificates & secrets in Azure)
• Tenant ID (from Azure AD overview page)

Step 4: Click Reconnect Account and complete the Microsoft login flow.

Step 5: If reconnection fails with "AADSTS50011: The reply URL specified in the request does not match," double-check the redirect URI in Azure AD exactly matches your n8n instance URL.

Build workflows that detect and refresh tokens before they expire. This eliminates manual intervention.

Enable Automatic Token Refresh

n8n automatically refreshes OAuth2 tokens if the service provides a refresh token. Verify this is enabled:

Step 1: Open any OAuth2 credential.

Step 2: Scroll to OAuth2 Parameters.

Step 3: Ensure Access Token URL and Refresh Token URL are populated. If empty, n8n cannot auto-refresh.

Step 4: For Google credentials, verify the scope includes offline_access or the equivalent for your service.

Build a Token Health Monitor Workflow

Create a dedicated workflow that checks token status and sends alerts before expiration.

Step 1: Add a Schedule Trigger node. Set it to run daily at 9 AM.

Step 2: Add an HTTP Request node to query n8n's API

:

Method: GET
URL: http://localhost:5678/api/v1/credentials
Authentication: Header Auth
Header Name: X-N8N-API-KEY
Header Value: [YOUR_API_KEY]

Step 3: Add a Code node to parse credentials and check expiration:

const credentials = $input.all();
const expiringCreds = [];
const now = new Date();
const warningThreshold = 7; // days

for (const cred of credentials) {
  if (cred.json.type.includes('OAuth2')) {
    const data = cred.json.data;
    if (data.oauthTokenData && data.oauthTokenData.expires_in) {
      const expiresAt = new Date(data.oauthTokenData.expires_in * 1000);
      const daysUntilExpiry = (expiresAt - now) / (1000 * 60 * 60 * 24);
      
      if (daysUntilExpiry < warningThreshold) {
        expiringCreds.push({
          name: cred.json.name,
          type: cred.json.type,
          daysRemaining: Math.floor(daysUntilExpiry)
        });
      }
    }
  }
}

return expiringCreds.map(c => ({ json: c }));

Step 4: Add a Slack or Email node to send alerts when credentials are expiring.

Step 5: Activate the workflow.

Use Service Accounts for Google Workspace

Service accounts bypass user-based OAuth entirely. Tokens don't expire as long as the service account remains active.

Step 1: In Google Cloud Console, go to IAM & Admin > Service Accounts.

Step 2: Click Create Service Account.

Step 3: Name it (e.g., "n8n-automation") and grant it the Editor role.

Step 4: Click Create Key and download the JSON key file.

Step 5: In n8n, create a Google Service Account credential (not OAuth2).

Step 6: Paste the entire JSON key file content into the Service Account JSON field.

Step 7: For Google Sheets access, share the specific sheets with the service account email (found in the JSON file as client_email).

Service accounts work for Google Sheets, Drive, Calendar, and Gmail (with domain-wide delegation).

Implement Credential Rotation

For high-security environments, rotate credentials every 30-60 days regardless of expiration.

Step 1: Create duplicate credentials with "_v2" suffix.

Step 2: Update workflows to use the new credentials.

Step 3: Test thoroughly in a staging environment.

Step 4: Deploy to production during a maintenance window.

Step 5: Delete old credentials after 7 days of successful operation.

Refresh tokens themselves can expire. When this happens, auto-refresh fails and you must manually reauthorize.

Google: Refresh tokens expire after 6 months of non-use or if the user revokes access.

Microsoft: Refresh tokens expire after 90 days of inactivity or 24 hours if the user changes their password.

Slack: Refresh tokens don't expire unless the app is uninstalled or the user revokes access.

Salesforce: Refresh tokens don't expire but can be revoked by administrators.

The solution: Set up the token health monitor workflow above. It catches refresh token expiration before workflows break.

When a production workflow fails due to token expiration:

1. Identify the failed credential (check execution logs)
2. Open the credential and click Reconnect Account
3. Complete the OAuth flow
4. Manually execute the workflow to verify the fix
5. Check execution history for any missed runs
6. Manually trigger missed executions if necessary
7. Document the incident and add the credential to your monitoring workflow

Keep OAuth client credentials (Client ID and Secret) in a password manager. You'll need them for emergency reconnections.