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

# Troubleshooting

> Solutions to common issues

## Data Sources

### Connection Failed

**Symptom**: Data source shows "Connection Failed" status.

**Solutions**:

1. **OAuth expired**: Re-authenticate by clicking the data source and selecting "Reconnect"
2. **Permissions changed**: Verify your account still has access to the data
3. **Service outage**: Check if the external service (Google Sheets, Salesforce, etc.) is operational

### Sync Not Updating

**Symptom**: Data appears stale or sync timestamp hasn't changed.

**Solutions**:

1. **Check sync schedule**: Syncs run automatically based on Fivetran configuration
2. **Manual refresh**: Click the refresh icon on the data source card
3. **Large dataset**: Initial syncs may take longer for large datasets

### File Upload Errors

**Symptom**: CSV or Excel file fails to upload.

**Solutions**:

1. **File size**: Maximum file size is 100MB
2. **Format issues**: Ensure CSV uses UTF-8 encoding
3. **Column headers**: First row must contain column names
4. **Special characters**: Remove or escape special characters in headers

## Data Layer

### AI Generation Stuck

**Symptom**: Data layer generation appears to hang.

**Solutions**:

1. **Wait**: Complex schemas may take 1-2 minutes to analyze
2. **Refresh**: Reload the page and check if generation completed
3. **Simplify**: Try with fewer tables selected initially

### Relationships Not Detected

**Symptom**: Expected linkages between tables don't appear.

**Solutions**:

1. **Column naming**: Ensure foreign key columns follow patterns like `customer_id`
2. **Data types**: Matching columns should have compatible types
3. **Manual creation**: Add relationships manually in the Linkages tab

### Publish Failed

**Symptom**: Unable to publish data layer changes.

**Solutions**:

1. **Validation errors**: Check the Review panel for specific issues
2. **Empty entities**: Entities must have at least one property
3. **Circular references**: Check for relationship loops

## Analytics Chat

### Query Returns No Results

**Symptom**: Question returns empty results unexpectedly.

**Solutions**:

1. **Check filters**: Review the SQL in the Logic view for unexpected WHERE clauses
2. **Date ranges**: Ensure your data includes the time period you're asking about
3. **Entity names**: Use terms that match your data layer definitions

### SQL Error

**Symptom**: Query fails with a SQL error message.

**Solutions**:

1. **Data type mismatch**: Check if you're comparing incompatible types
2. **Null values**: Some aggregations fail with null data
3. **Rephrase question**: Try asking the question differently

### Slow Queries

**Symptom**: Queries take a long time to return.

**Solutions**:

1. **Large datasets**: Consider adding date filters to your questions
2. **Complex aggregations**: Break down complex questions into simpler parts
3. **Data layer optimization**: Review entity definitions for unnecessary joins

## MCP Integration

### Server Not Connecting

**Symptom**: Claude Desktop or VS Code can't connect to AstroBee MCP.

**Solutions**:

1. **API Key**: Verify your API key is correct in Settings > Integrations
2. **URL format**: Ensure you're using the correct server URL from the MCP tab
3. **Firewall**: Check if your network allows outbound connections to AstroBee

### Tools Not Available

**Symptom**: AstroBee tools don't appear in your AI assistant.

**Solutions**:

1. **Restart**: Restart Claude Desktop or VS Code after configuration changes
2. **Config syntax**: Verify your `claude_desktop_config.json` or `settings.json` syntax
3. **Server status**: Check that the MCP server URL is accessible

## Account & Settings

### Can't Invite Team Members

**Symptom**: Invite button doesn't work or invites aren't received.

**Solutions**:

1. **Email delivery**: Check spam/junk folders
2. **Permissions**: Verify you have admin access to the organization
3. **Domain restrictions**: Some organizations restrict external invites

### OAuth Provider Not Working

**Symptom**: Custom OAuth integration fails.

**Solutions**:

1. **Redirect URI**: Ensure the callback URL is correctly configured
2. **Credentials**: Verify client ID and secret are correct
3. **Scopes**: Check that required scopes are enabled

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="envelope" href="mailto:support@astrobee.ai">
    Email our support team
  </Card>

  <Card title="In-App Support" icon="message" href="/support">
    Send a message from within AstroBee
  </Card>
</CardGroup>