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

# Troubleshooting

> Common integration issues and solutions

General guidelines for troubleshooting integration issues across all services.

## Common Issues

<AccordionGroup>
  <Accordion title="Connection Failed" icon="circle-x">
    ### Possible Causes

    * Invalid credentials (API key, OAuth token)
    * Expired authentication
    * Incorrect configuration
    * Network connectivity issues

    ### Solutions

    <Steps>
      <Step title="Verify Credentials">
        Check that credentials are correct and haven't expired
      </Step>

      <Step title="Reconnect">
        Try disconnecting and reconnecting the integration
      </Step>

      <Step title="Check Configuration">
        Verify all required fields (URLs, IDs, etc.) are correct
      </Step>

      <Step title="Test Network">
        Ensure network connectivity to the external service
      </Step>
    </Steps>

    <Tip>
      For OAuth integrations, try clearing browser cache and cookies before reconnecting.
    </Tip>
  </Accordion>

  <Accordion title="Permission Denied" icon="shield-x">
    ### Possible Causes

    * Missing required permissions
    * User revoked access
    * Admin restrictions
    * Resource access limitations

    ### Solutions

    <Steps>
      <Step title="Review Permissions">
        Check that all required scopes were granted
      </Step>

      <Step title="Reconnect with Full Permissions">
        Disconnect and reconnect, approving all requested permissions
      </Step>

      <Step title="Verify Access">
        Confirm user has access to the specific resources
      </Step>

      <Step title="Check Admin Settings">
        For enterprise accounts, verify admin hasn't blocked the integration
      </Step>
    </Steps>

    <Warning>
      Some integrations require admin approval. Contact your IT administrator if needed.
    </Warning>
  </Accordion>

  <Accordion title="Rate Limit Exceeded" icon="gauge">
    ### Possible Causes

    * Too many API requests in short time
    * Concurrent flow executions
    * Bulk operations without throttling
    * Service quota exceeded

    ### Solutions

    <Tabs>
      <Tab title="Flow Design">
        * Add delays between API calls
        * Use batch operations when available
        * Implement exponential backoff
        * Reduce polling frequency
      </Tab>

      <Tab title="Monitoring">
        * Track API usage in flow logs
        * Monitor rate limit headers
        * Set up alerts for rate limits
        * Review service quotas
      </Tab>

      <Tab title="Optimization">
        * Cache responses when possible
        * Filter data at source
        * Use pagination efficiently
        * Combine multiple operations
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Authentication Expired" icon="clock">
    ### Possible Causes

    * OAuth token expired (shouldn't happen with auto-refresh)
    * API key rotated
    * Client secret expired
    * Session timeout

    ### Solutions

    <Steps>
      <Step title="Reconnect Integration">
        Go to Settings → Integrations → Reconnect
      </Step>

      <Step title="Update Credentials">
        For API keys, enter new credentials
      </Step>

      <Step title="Check Expiration">
        For Service Principals, check client secret expiration
      </Step>

      <Step title="Test">
        Run a test flow to verify connection
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Integration Not Found in Flow" icon="search-x">
    ### Possible Causes

    * Integration not connected in workspace
    * Wrong workspace selected
    * Integration was disconnected
    * Node requires specific integration

    ### Solutions

    <Steps>
      <Step title="Check Connection">
        Verify integration is connected: Settings → Integrations
      </Step>

      <Step title="Verify Workspace">
        Ensure you're in the correct workspace
      </Step>

      <Step title="Reconnect">
        Connect the integration if disconnected
      </Step>

      <Step title="Refresh Flow">
        Refresh the flow editor to see updated integrations
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Data Not Syncing" icon="refresh-ccw">
    ### Possible Causes

    * Permission issues
    * API changes
    * Filter or query errors
    * Data format mismatches

    ### Solutions

    <Tabs>
      <Tab title="Permissions">
        * Verify read/write permissions
        * Check resource-level access
        * Review sharing settings
        * Test with simpler operations
      </Tab>

      <Tab title="Configuration">
        * Review filter settings
        * Check field mappings
        * Verify data formats match
        * Test with sample data
      </Tab>

      <Tab title="Debugging">
        * Check flow execution logs
        * Inspect node outputs
        * Test integration directly
        * Review API documentation
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## Debugging Steps

<Steps>
  <Step title="Check Connection Status">
    Verify integration shows as "Connected" in Settings → Integrations
  </Step>

  <Step title="Review Flow Logs">
    Examine execution logs for error messages and details
  </Step>

  <Step title="Test Integration Directly">
    Create a minimal test flow with just the integration node
  </Step>

  <Step title="Verify Permissions">
    Confirm all required permissions are granted
  </Step>

  <Step title="Check External Service">
    Verify the external service is operational (status pages)
  </Step>

  <Step title="Review Recent Changes">
    Check if credentials were rotated or permissions changed
  </Step>
</Steps>

***

## Service-Specific Issues

<Tabs>
  <Tab title="Google Workspace">
    **Common Issues:**

    | Issue                 | Solution                                                 |
    | :-------------------- | :------------------------------------------------------- |
    | Admin restrictions    | Contact Google Workspace admin to allow third-party apps |
    | Quota exceeded        | Check Google API quotas in Cloud Console                 |
    | Redirect URI mismatch | Contact Noxus support to verify OAuth configuration      |
    | Account not eligible  | Ensure using Google Workspace (not personal Gmail)       |
  </Tab>

  <Tab title="Microsoft 365">
    **Common Issues:**

    | Issue                   | Solution                            |
    | :---------------------- | :---------------------------------- |
    | Admin approval required | Forward consent request to IT admin |
    | Invalid tenant          | Verify tenant ID is correct         |
    | Client secret expired   | Generate new secret in Azure Portal |
    | MFA issues              | Complete MFA before connecting      |
  </Tab>

  <Tab title="Slack">
    **Common Issues:**

    | Issue               | Solution                                             |
    | :------------------ | :--------------------------------------------------- |
    | Bot not in channel  | Use `/invite @Noxus` in channel                      |
    | Missing scope       | Disconnect and reconnect with additional permissions |
    | Rate limited        | Space out messages, check Slack tier limits          |
    | Workspace not found | Verify workspace URL is correct                      |
  </Tab>

  <Tab title="GitHub">
    **Common Issues:**

    | Issue                | Solution                                                   |
    | :------------------- | :--------------------------------------------------------- |
    | Repository not found | Update repository access in GitHub Settings → Applications |
    | API rate limit       | Wait for rate limit reset (5000 requests/hour)             |
    | Push rejected        | Verify write permissions and branch protection rules       |
    | Token expired        | Reconnect OAuth or generate new Personal Access Token      |
  </Tab>
</Tabs>

***

## Getting Help

<CardGroup cols={2}>
  <Card title="Check Service Status" icon="activity">
    Verify external service is operational

    * Google Workspace Status
    * Microsoft 365 Status
    * GitHub Status
    * Slack Status
  </Card>

  <Card title="Review Documentation" icon="book">
    Check provider-specific guides:

    * [Microsoft 365](/integrations/providers/microsoft)
    * [Google Workspace](/integrations/providers/google)
    * [Atlassian](/integrations/providers/atlassian)
    * [Developer Tools](/integrations/providers/developer-tools)
  </Card>

  <Card title="Flow Logs" icon="file-text">
    Examine execution logs for detailed error messages and stack traces
  </Card>

  <Card title="Contact Support" icon="mail" href="mailto:help@noxus.ai">
    Reach out to Noxus support with:

    * Integration name
    * Error message
    * Flow execution logs
    * Steps to reproduce
  </Card>
</CardGroup>

***

## Best Practices for Reliability

<Tabs>
  <Tab title="Error Handling">
    **Build resilient flows:**

    * Enable "Continue on Error" for integration nodes
    * Add retry logic with exponential backoff
    * Implement fallback paths
    * Log errors for debugging
  </Tab>

  <Tab title="Monitoring">
    **Track integration health:**

    * Monitor success/failure rates
    * Set up alerts for repeated failures
    * Track API usage and quotas
    * Review logs regularly
  </Tab>

  <Tab title="Maintenance">
    **Keep integrations healthy:**

    * Rotate credentials before expiration
    * Test integrations after service updates
    * Update permissions when needed
    * Remove unused connections
  </Tab>
</Tabs>

***

<Card title="Authentication Guide" icon="key" href="/integrations/authentication">
  Learn more about authentication methods
</Card>