Connection Issues

Having trouble connecting services or integrations not working? Here's how to diagnose and fix connection issues.

General Connection Troubleshooting

Step 1: Check the Basics

Before diving deeper:

1. Is the external service online? Check their status page
2. Is your internet connection stable?
3. Are you logged into the service you're connecting?
4. Did you grant all requested permissions?

Step 2: Reconnect the Integration

Often the simplest fix:

1. Go to Settings → Integrations
2. Find the problematic integration
3. Click "Disconnect"
4. Wait 10 seconds
5. Click "Connect" again
6. Complete the authorization flow

Step 3: Clear Browser State

If reconnecting doesn't work:

1. Clear cookies for the service domain
2. Log out of the service in another tab
3. Clear Billix cookies
4. Try connecting again in a fresh browser tab

Service-Specific Issues

Gmail / Google Services

"Access blocked" error:

• Google may block connections from new apps
• Go to myaccount.google.com → Security
• Check "Third-party apps with account access"
• Ensure Billix is listed and has access

"Refresh token expired":

• Google tokens expire after some time
• Disconnect and reconnect Gmail integration
• Re-authorize all permissions

Can't see all emails:

• Check if you granted "Read" permission
• Verify the correct Gmail account is connected
• Some organizational accounts block third-party access

Slack

"Missing scopes" error:

• Slack permissions were partially granted
• Disconnect Slack in Billix
• In Slack: Apps → Billix → Remove
• Reconnect and approve all requested scopes

Bot not responding in channel:

• Invite the Billix bot to the channel: /invite @Billix
• Check bot has permission to post
• Verify channel isn't restricted

Can't connect workspace:

• You may need admin approval
• Contact your Slack workspace administrator
• Some workspaces block third-party apps

Discord

"Missing permissions" error:

• You need "Manage Server" permission
• Ask a server admin to connect Discord
• Or have them grant you the permission

Bot offline in server:

• Check if bot was kicked from server
• Reconnect the Discord integration
• Re-invite bot to the server

GitHub

"Repository not found":

• Check you have access to the repository
• Verify the repository name is correct
• Private repos need explicit permission

"Insufficient permissions":

• Disconnect and reconnect GitHub
• Grant access to the specific repositories
• Organization repos may need admin approval

Rate limited:

• GitHub limits API calls
• Wait an hour and try again
• Reduce frequency of GitHub-related agents

Notion

"Page not found":

• Share the page with Billix integration
• In Notion: Page menu → Connections → Add Billix
• Check page exists and wasn't deleted

Can't see databases:

• Databases must be explicitly shared
• Open the database, not just containing page
• Share via Connections menu

"Unauthorized":

• Reconnect Notion integration
• Re-authorize when prompted
• Check Notion account is active

Google Drive

"File not accessible":

• File must be shared with Billix
• Check file permissions in Drive
• Owned files should work automatically

Can't upload:

• Check you granted write permission
• Verify storage quota isn't full
• Try a smaller file first

Google Calendar

"Calendar not found":

• Check calendar ID is correct
• Ensure calendar is shared with Billix
• Primary calendar should work by default

Events not syncing:

• Reconnect Google Calendar
• Check timezone settings
• Verify calendar permissions

Linear

"Team not found":

• Check team ID is correct
• Verify you're a member of the team
• Reconnect Linear integration

Can't create issues:

• Check you have permission to create issues
• Verify project exists
• Team may have restrictions

Jira

"Project not found":

• Verify project key is correct
• Check your Jira permissions
• Project may be archived

"Authentication failed":

• Jira uses API tokens, not passwords
• Generate new API token in Jira settings
• Reconnect with fresh token

OAuth Flow Issues

Popup Blocked

Symptom: Nothing happens when clicking "Connect"

Solution:

1. Check for popup blocker notification
2. Allow popups for Billix
3. Click "Connect" again
4. Or: Right-click → Open in new tab

Stuck on Authorization Page

Symptom: Service authorization page doesn't complete

Solution:

1. Don't close the popup too early
2. Wait for redirect to complete
3. If stuck, close and try again
4. Try different browser

"State mismatch" Error

Symptom: Security error during OAuth

Solution:

1. This is a security feature
2. Clear cookies and try again
3. Don't reuse old authorization tabs
4. Complete flow in single session

Redirect Loop

Symptom: Page keeps redirecting without completing

Solution:

1. Clear all Billix cookies
2. Clear service cookies
3. Try incognito/private window
4. Disable browser extensions

Firewall and Network Issues

Corporate Firewall Blocking

Symptom: Works at home but not at work

Solution:

1. Check if your company blocks third-party apps
2. Ask IT to whitelist Billix domains
3. Try on a non-corporate network
4. Use mobile data as test

VPN Interference

Symptom: Connections fail with VPN on

Solution:

1. Some VPNs block OAuth flows
2. Try disconnecting VPN temporarily
3. Or use split tunneling
4. Check VPN isn't blocking required domains

When to Contact Support

Contact support if:

• You've tried all troubleshooting steps
• The issue persists across browsers/devices
• You see an error not documented here
• An integration worked before and suddenly stopped

Provide:

• Which integration you're connecting
• The exact error message
• Steps you've already tried
• Screenshots if possible

Next Steps

• Contact Support
• Common Issues
• Managing Integrations