> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerotwo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors Troubleshooting

> Fix common issues with ZeroTwo's OAuth integrations.

Most connector issues fall into a few predictable patterns. Find your issue below and follow the resolution steps.

<Accordion title="OAuth flow failed — redirect didn't return to ZeroTwo">
  After clicking **Allow** on the app's authorization page, you were not returned to ZeroTwo (e.g., you see a blank page, an error from the app, or you end up on the app's homepage instead).

  **Causes and fixes:**

  1. **Third-party cookies are blocked.** OAuth redirects rely on cookies to maintain session state. If your browser blocks third-party cookies (common in Safari and hardened Chrome profiles), the redirect can fail.
     * In Chrome: Settings → Privacy and Security → Third-party cookies → Allow third-party cookies (or add an exception for `zerotwo.ai`)
     * In Safari: Settings → Privacy → uncheck "Prevent cross-site tracking" temporarily
     * In Firefox: Settings → Privacy → uncheck "Enhanced Tracking Protection" for `zerotwo.ai`

  2. **Pop-up blocker intercepted the window.** If the OAuth flow opened in a new window or tab, a pop-up blocker may have closed it.
     * Allow pop-ups for `zerotwo.ai` in your browser settings and try again.

  3. **Browser extensions interfering.** Ad blockers, privacy extensions (uBlock Origin, Privacy Badger), or VPN browser extensions can interfere with redirect flows.
     * Temporarily disable extensions and try connecting again.

  4. **Try a different browser.** If the above steps don't resolve it, try the connection in a clean browser (e.g., Chrome with no extensions).
</Accordion>

<Accordion title="Connector shows 'Needs reauthorization'">
  The connector tile shows a yellow or red "Needs reauthorization" badge and ZeroTwo cannot use the app.

  **Why this happens:**

  * The OAuth access token expired and the refresh token is no longer valid
  * You (or an admin) revoked ZeroTwo's access from within the app's settings
  * The app's OAuth server rotated keys or changed token policies
  * You changed your password on the connected app (some apps invalidate all tokens on password change)

  **Fix:**

  1. Go to **Settings → Connectors**
  2. Click the affected connector
  3. Click **Reconnect**
  4. Complete the OAuth authorization flow again

  After reconnecting, any tasks or agents that were failing due to this connector will resume on their next run.
</Accordion>

<Accordion title="Connected app not appearing in Agent Mode">
  You've connected an app in Settings → Connectors, but when you run Agent Mode, the agent doesn't seem to have access to it.

  **Check these:**

  1. **Is the connector showing as "Connected"?**
     Go to Settings → Connectors and verify the app shows a green "Connected" status — not "Needs reauthorization" or "Error".

  2. **For standard Agent Mode chats**: any connected app is automatically available to the agent. You don't need to configure anything else. Try explicitly asking the agent to use the app: "Use my Notion connector to find the project brief."

  3. **For Custom Agents**: Custom Agents must have connectors explicitly assigned in their configuration. Go to the Custom Agent's settings and verify the connector is added to the agent's allowed tools list.

  4. **Check your scopes**: the agent may be trying to perform an action the authorized scopes don't cover. See the "Agent can't perform an action" accordion below.
</Accordion>

<Accordion title="@ mention not showing app in dropdown">
  You type `@` in a chat but the connected app doesn't appear in the mention dropdown.

  **Fixes:**

  1. **Verify the app is connected.** Go to **Settings → Connectors** and confirm the app shows "Connected". If it shows any other status, reconnect it first.

  2. **Type more of the app name.** The @ mention dropdown filters as you type. After typing `@`, start typing the first few letters of the app name (e.g., `@Goo` for Google Drive, `@Git` for GitHub).

  3. **Refresh the page.** If you just connected the app in the same session, a page refresh may be needed to populate the @ mention list.

  4. **Check for typos in the app name.** Search for the app's exact name as it appears in Settings → Connectors.
</Accordion>

<Accordion title="Agent can't perform an action even though the app is connected">
  ZeroTwo says something like "I don't have permission to do that" or the action silently fails, even though the connector is Connected.

  **This is almost always a scopes issue.**

  OAuth connections are scoped — you may have authorized ZeroTwo to *read* data from an app but not *write* to it, or vice versa. Common examples:

  | Symptom                                               | Likely cause                             |
  | ----------------------------------------------------- | ---------------------------------------- |
  | Can read Gmail but can't send emails                  | Connected with `gmail.readonly` only     |
  | Can read GitHub repos but can't create issues         | Connected without `issues:write` scope   |
  | Can view Google Drive files but can't create new ones | Connected with `drive.readonly` only     |
  | Can view Notion pages but can't update them           | Connected without `update_content` scope |

  **Fix:**

  1. Go to **Settings → Connectors**
  2. Click the app → note the currently authorized scopes
  3. Click **Disconnect** to remove the existing (limited) connection
  4. Click **Connect** again — during the new OAuth flow, you'll be asked to authorize a broader set of scopes
  5. Review and approve the updated permissions

  If you're unsure which scopes are needed, try reconnecting and approving all requested permissions.
</Accordion>

<Accordion title="Disconnected an app but it's still accessible">
  You disconnected a connector but the app still appears to be accessible (e.g., @ mentions still work or an agent can still use it).

  **Steps to resolve:**

  1. **Wait a moment and refresh.** Disconnection takes effect immediately on ZeroTwo's side, but your current browser tab may be serving cached state. Do a hard refresh (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows).

  2. **Verify the disconnection.** Go to **Settings → Connectors** and confirm the app no longer shows "Connected". If it still shows connected, the disconnection may not have completed — try clicking Disconnect again.

  3. **Check for multiple connected accounts.** If you connected the same app twice (e.g., two Google accounts), disconnecting one may leave the other active. Review all entries for that app in the connectors list.

  4. **If the issue persists**: disconnect the app again, wait 30 seconds, then refresh. If it remains accessible after that, contact ZeroTwo support.
</Accordion>

***

## Still having trouble?

If none of the above resolves your issue:

* Navigate to **Settings → Connectors → \[app name]** and use the help link in the connector detail panel for app-specific guidance
* Check the [ZeroTwo status page](https://zerotwo.ai/status) for any known outages affecting specific integrations
* Contact support with the name of the app you're trying to connect and a description of the error you're seeing