Troubleshooting

​

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?