Troubleshooting

Authentication Issues

”Authorization failed” when connecting a connector

Cause: The OAuth flow was interrupted or the authorization was denied.

Fix:

1. Click the connector in your Dashboard and select Reconnect
2. Complete the full OAuth flow, making sure to click Allow (or Authorize) on the provider’s page
3. If the issue persists, try signing out of the provider in your browser first, then reconnecting

”Session expired” or “Token invalid”

Cause: The connector’s access token has expired and automatic refresh failed.

Fix:

1. Go to Connectors in your Dashboard
2. Click the affected connector and select Reconnect
3. Complete the OAuth flow again — this issues a fresh token

Connector Sync Issues

Content not appearing after connecting

Cause: Initial sync may still be in progress, or the sync hasn’t been triggered yet.

Fix:

1. Wait a few minutes — large workspaces (100+ documents) can take 5–10 minutes for initial indexing
2. Go to Connectors → click the connector → Sync Now to trigger a manual sync
3. Check the sync status indicator — a red indicator means the sync failed (see error message for details)

New documents not appearing

Cause: Knowledge Raven syncs on a scheduled cycle. New content added after the last sync won’t appear immediately.

Fix: Trigger a manual sync from the Connectors page.

Notion pages not found

Cause: Notion requires explicit page sharing with the integration. Pages not explicitly shared won’t be accessible.

Fix: In Notion, open the page → click Share → find the Knowledge Raven integration → grant access. Then trigger a manual sync.

GitHub files not indexed

Cause: Files may be binary, over 50 MB, or have an unsupported extension.

Fix: Check the file extension against the supported list. Binary files and large data dumps are intentionally excluded.

Dropbox file types not indexed

Cause: Only 7 file formats are supported: PDF, DOCX, TXT, MD, CSV, PPTX, XLSX.

Fix: Convert files to a supported format, or use a different connector for that content.

Plan Limit Errors

”Document limit reached” (HTTP 402)

Your workspace has reached the document limit for your current plan.

Fix:

• Delete unused documents to free up space, or
• Upgrade your plan in Settings → Plan

”Query limit reached” (HTTP 402)

Free plan users have 100 MCP queries per user per month.

Fix: Upgrade to the Pro plan for unlimited queries — Settings → Plan → Upgrade.

”User limit reached” (HTTP 402)

Your workspace has reached the user limit for your plan.

Fix: Remove inactive users in Settings → Users, or upgrade to a higher plan.

Agent Not Finding Relevant Content

Check 1: Make sure the relevant connector is connected and synced — go to Connectors and verify the status.

Check 2: Try rephrasing your question. Precision search (search_knowledge_base) works best with specific keywords. If your question is broad, use explorative phrasing to trigger broad_search.

Check 3: Verify the document is in a knowledge base your account has access to — list_knowledge_bases will show all accessible KBs.

Getting Help

If you can’t resolve an issue with this guide, contact support:

• Email: support@birdflai.com
• In-app: Settings → Support

Please include your workspace ID and a description of the issue for faster resolution.