> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-mtd-v5-docs-sdk-shape.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector troubleshooting

> Diagnose and resolve common issues with Google Drive, Gmail, Notion, and OneDrive connectors

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

## Quick health check

Check if your connectors are working properly:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { connectors } = await supermemory.connectors.list("user-123")

  connectors.forEach(connector => {
    console.log(`${connector.provider}: ${connector.account} - last sync ${connector.latestRun?.system.status ?? "never"}`)
  })

  // Inspect a failing connector's recent runs and the items that failed
  const failing = connectors.filter(connector => connector.latestRun?.system.status === "failed")
  for (const connector of failing) {
    const detail = await supermemory.connectors.get("user-123", connector.id, {
      include: "syncs",
    })
    console.log(`⚠️ ${connector.provider}: ${detail.latestRun?.error}`)
    console.log(detail.syncs)
  }

  // Check for stuck documents in the namespace
  const { documents } = await supermemory.list("user-123", "documents")
  const stuck = documents.filter(doc => doc.system.status === "failed")
  if (stuck.length > 0) {
    console.log(`⚠️ ${stuck.length} documents failed to process`)
  }
  ```

  ```python Python theme={null}
  connectors = client.connectors.list("user-123").connectors

  for connector in connectors:
      status = connector.latest_run.system.status if connector.latest_run else "never"
      print(f"{connector.provider}: {connector.account} - last sync {status}")

  # Inspect a failing connector's recent runs and the items that failed
  failing = [c for c in connectors if c.latest_run and c.latest_run.system.status == "failed"]
  for connector in failing:
      detail = client.connectors.get("user-123", connector.id, include=["syncs"])
      print(f"⚠️ {connector.provider}: {detail.latest_run.error}")
      print(detail.syncs)

  # Check for stuck documents in the namespace
  documents = client.list("user-123", "documents").documents
  stuck = [doc for doc in documents if doc.system.status == "failed"]
  if stuck:
      print(f"⚠️ {len(stuck)} documents failed to process")
  ```

  ```bash cURL theme={null}
  # List connectors in the namespace
  curl "https://api.supermemory.ai/ns/user-123/connectors" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

  # Read one connector with its recent sync runs
  curl "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?include=syncs" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

  # Check document status in the namespace
  curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"filter": {"field": "source", "operator": "eq", "value": "notion"}}'
  ```
</CodeGroup>

<Note>
  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`.
</Note>

## 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:

```typescript theme={null}
// correct - exact match with OAuth app settings
const connector = await supermemory.connectors.create("user-123", {
  provider: "notion",
  redirectUrl: "https://yourapp.com/auth/notion/callback"
})

// Wrong - URL doesn't match
// redirectUrl: "https://yourapp.com/callback"
```

**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:

```typescript theme={null}
// Force a sync for the connector
await supermemory.connectors.sync("user-123", "PTzGiUYei7pgzg5buzZHgA")
// 409 means a sync is already running; wait for latestRun.system.status to change
```

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:

```typescript theme={null}
// Delete and recreate the connector
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})

const next = await supermemory.connectors.create("user-123", {
  provider: "google-drive",
  redirectUrl: "https://yourapp.com/callback"
})

// User must re-authenticate
if (next.authorization) window.location.href = next.authorization.url
```

### Sync takes too long

**Problem:** Hundreds of documents taking hours to sync

**Solution:** Set reasonable document limits:

```typescript theme={null}
const connector = await supermemory.connectors.create("user-123", {
  provider: "onedrive",
  redirectUrl: "https://yourapp.com/callback"
  documentLimit: 500, // Start with fewer documents
})

// Raise it later without reconnecting
await supermemory.connectors.update("user-123", connector.id, {
  documentLimit: 2000,
})
```

## 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:

```typescript theme={null}
await supermemory.connectors.sync("user-123", "PTzGiUYei7pgzg5buzZHgA")
```

**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

```typescript theme={null}
// Re-authenticate to get fresh tokens
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})

const next = await supermemory.connectors.create("user-123", {
  provider: "gmail",
  redirectUrl: "https://yourapp.com/callback"
})
```

**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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.