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 does not show it Solution: A pending OAuth connector is not returned by list until the user finishes authorization. connectors.get still returns it with system.status: "pending_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: The provider always redirects to Supermemory’s callback, not to your redirectUrl. If you use a custom OAuth application, its redirect URI must be exactly https://api.supermemory.ai/v3/connections/auth/callback/{provider}. Your redirectUrl is where Supermemory sends the user after it handles that callback, and must be an http or https URL:
Prevention:
  • Use HTTPS for production URLs
  • Register https://api.supermemory.ai/v3/connections/auth/callback/{provider} in your custom 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 manual sync works:
  1. Real-time sync uses Google Cloud Pub/Sub webhooks
  2. Watch subscriptions expire after 7 days (supermemory auto-renews)
  3. Real-time updates cover only the labels selected for the connector
  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
Max Plan Required Error Gmail connector requires Max Plan or above. If you see access errors:
  • Verify your organization has the required plan
  • Upgrade from Billing in the console

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