Skip to main content
Quick guide to resolve common connector issues with authentication, syncing, and permissions.

Quick health check

Check if your connectors are working properly:
There is no per-connector document list in v5. supermemory.list(namespace, "documents") returns every document in the namespace; read each document’s system.status.

Common issues

Connector Missing From List

Problem: connectors.create returned an id, but connectors.list and connectors.get do not show it Solution: A pending OAuth connector is not visible in list or get until the user finishes authorization. Send the user to authorization.url before authorization.expiresAt. If the link expired, create the connector again.

OAuth callback fails

Problem: “Invalid redirect URI” error after user grants permissions Solution: Ensure your redirect URL matches EXACTLY what’s configured in your OAuth app:
Prevention:
  • Use HTTPS for production URLs
  • Copy the exact URL from your OAuth app settings
  • Test the flow in development first

Documents not syncing

Problem: Documents stuck in “queued” or “extracting” status for over 30 minutes Solution: Trigger a manual sync:
If documents consistently fail:
  • Read latestRun.error and include: "syncs" for the failed items
  • Check if files are over 50MB (may timeout)
  • Verify you have permission to access the documents
  • Ensure the document type is supported

Permission denied errors

Problem: Some documents show “permission denied” or aren’t syncing Solution: Re-authenticate with proper permissions:

Sync takes too long

Problem: Hundreds of documents taking hours to sync Solution: Set reasonable document limits:

Provider-specific issues

Google Drive

Shared Drive Issues Shared drives require special permissions. Make sure:
  • User has access to the shared drive
  • OAuth app has drive.readonly scope
  • User is a member of the shared drive
Picker Not Completed With the default scoped sync, syncs may skip the connector until the user finishes the file picker. Read the connector with include: "picker" and send the user to picker.url.

Notion

Database Not Syncing Notion databases need explicit permission. If databases aren’t syncing:
  1. Go to Notion workspace settings
  2. Find your integration under “Connections”
  3. Click on the integration
  4. Select specific pages/databases to share
  5. Re-sync after granting access
Workspace Access For full workspace access, a workspace admin must:
  1. Approve the integration
  2. Grant access to all pages
  3. Enable “Read content” permission

OneDrive

Business vs Personal Accounts Business accounts may have additional restrictions:
  • Admin consent might be required
  • Some SharePoint sites may be restricted
  • Compliance policies may block certain files

Gmail

Real-time Sync Not Working If emails aren’t syncing in real-time but scheduled/manual sync works:
  1. Real-time sync uses Google Cloud Pub/Sub webhooks
  2. Watch subscriptions expire after 7 days (supermemory auto-renews)
  3. Only INBOX label triggers real-time updates
  4. Trigger a manual sync to verify the connector is healthy:
Missing Refresh Token If Gmail stops syncing after initial setup:
  1. The user may have revoked app access in Google Account settings
  2. Delete and recreate the connector
  3. Ensure user completes full OAuth consent flow
Scale Plan Required Error Gmail connector requires Scale Plan or Enterprise Plan. If you see access errors:
  • Verify your organization has the required plan
  • Contact support to upgrade your plan

Best practices

  1. Set reasonable document limits - Start with 500-1000 documents
  2. Use one namespace per user or tenant - Makes debugging easier
  3. Monitor latestRun - Check weekly for failed syncs
  4. Handle rate limits gracefully - Implement exponential backoff
  5. Test OAuth in development - Ensure redirect URLs work before production