Troubleshooting

This guide helps you diagnose and resolve common issues with FluxCascade.

Connection Issues

Connection Shows "Expired"

Symptoms:

• Connection status shows "Expired" or "Error"
• Syncs fail with authentication errors
• "Invalid token" or "Unauthorized" messages

Solutions:

1. Reconnect the integration:

   • Go to Connections
   • Click on the expired connection
   • Click Reconnect
   • Re-authorize in the popup window

2. Check if access was revoked:

   • Log into the external system (HubSpot, Jobber, etc.)
   • Check connected apps/integrations settings
   • Look for FluxCascade and verify it's still authorized

3. Verify user permissions:

   • Ensure your user account has API access
   • Some platforms require Admin permissions

Connection Stuck on "Connecting"

Symptoms:

• OAuth popup doesn't complete
• Connection status never updates
• Spinning/loading indicator

Solutions:

1. Check popup blockers:

   • Allow popups for fluxcascade.com
   • Try disabling browser extensions

2. Clear browser cache:

   • Clear cookies for both FluxCascade and the external platform
   • Try in an incognito/private window

3. Try a different browser:

   • Sometimes browser-specific issues occur
   • Chrome and Firefox work best

"Permission Denied" or "Insufficient Scope"

Symptoms:

• Sync fails with permission errors
• Can't access certain objects or fields

Solutions:

1. Reconnect with proper permissions:

   • Disconnect the connection
   • Reconnect and ensure you approve all requested permissions
   • Don't uncheck any scopes during authorization

2. Check your role in the external system:

   • Verify you have Admin or appropriate role
   • Some objects require specific permissions

Sync Issues

Syncs Not Running

Symptoms:

• Scheduled syncs don't execute
• "Sync Now" button doesn't work
• No new sync jobs appearing

Solutions:

1. Verify mapping is active:

   • Go to Mappings
   • Check the mapping is toggled ON
   • Inactive mappings won't sync

2. Check connection health:

   • Both source and target connections must be "Active"
   • Reconnect any expired connections

3. Verify schedule configuration:

   • Go to mapping Settings
   • Confirm schedule is enabled
   • Check the frequency and next run time

4. Check for queued syncs:

   • A sync might be queued behind others
   • Check Syncs page for pending jobs

Syncs Taking Too Long

Symptoms:

• Syncs run for hours
• Timeouts occurring
• High latency

Solutions:

1. Use incremental syncs:

   • Edit mapping settings
   • Enable Incremental Sync
   • Only changed records will process

2. Reduce field count:

   • Remove unnecessary field pairs
   • Only sync essential fields

3. Check external system status:

   • The connected platform might be slow
   • Check their status page

4. Increase sync frequency:

   • More frequent syncs = fewer records per sync
   • Each sync runs faster

Records Not Syncing

Symptoms:

• Some records missing in target
• Record count doesn't match
• Specific records never appear

Solutions:

1. Check filters:

   • Review mapping filter criteria
   • Records might be excluded by filters

2. Verify matching:

   • Records might be updating existing rather than creating new
   • Check matching field values

3. Review sync logs:

   • Go to Syncs → [Job] → Logs
   • Look for specific record errors

4. Check required fields:

   • Target system might require fields that are empty
   • Add default values or fix source data

Duplicate Records Created

Symptoms:

• Same contact/record appears multiple times
• Duplicates in target system

Solutions:

1. Improve matching strategy:

   • Use a unique field like email for matching
   • Consider using External ID storage

2. Check for duplicate sources:

   • Duplicates might exist in source system
   • Clean source data before syncing

3. Verify matching field values:

   • If email changed, match may fail
   • Use a stable identifier

Data Issues

Wrong Data Being Synced

Symptoms:

• Field values incorrect
• Data appearing in wrong fields
• Unexpected transformations

Solutions:

1. Review field mapping:

   • Check source → target field pairs
   • Verify correct fields are mapped

2. Check transformations:

   • Review applied transforms
   • Test transform output

3. Verify field types:

   • Number fields shouldn't map to text fields without transform
   • Date formats might need conversion

Transformation Errors

Symptoms:

• "Transform failed" errors
• Fields syncing as empty
• Data format issues

Solutions:

1. Check input data:

   • Transformation might not handle all input formats
   • Example: phone transform expects digits

2. Add fallback handling:

   • Enable Skip on error for the field
   • Or set a default value

3. Review transform documentation:

   • Verify the transform is appropriate for your data
   • Consider a different transform

Missing or Empty Fields

Symptoms:

• Fields appear empty in target
• Data exists in source but not syncing

Solutions:

1. Verify field pair configuration:

   • Ensure field is included in mapping
   • Check field direction (bidirectional vs one-way)

2. Check field permissions:

   • Some fields might be read-only
   • API might not expose certain fields

3. Review source data:

   • Field might actually be empty in source
   • Check the raw data

Webhook Issues

Webhooks Not Triggering Syncs

Symptoms:

• Real-time sync not working
• Changes not syncing immediately
• Webhook deliveries not showing

Solutions:

1. Verify webhook registration:

   • Go to Connections → [Connection] → Webhooks
   • Confirm webhooks are "Active"

2. Check mapping settings:

   • Ensure Real-time Sync is enabled
   • Verify mapping is active

3. Test with manual change:

   • Make a change in the source system
   • Check Settings → Webhooks → Deliveries

4. Re-register webhooks:

   • Disable and re-enable Real-time Sync
   • This re-registers webhook subscriptions

Webhook Delivery Failures

Symptoms:

• Failed deliveries in webhook log
• 5xx errors
• Timeout errors

Solutions:

1. Check endpoint status:

   • For outbound webhooks, verify your endpoint is running
   • Ensure it responds within 30 seconds

2. Review error messages:

   • Check specific error codes
   • Common: 500 (server error), 503 (unavailable)

3. Retry failed deliveries:

   • Go to Settings → Webhooks → Deliveries
   • Select failed webhooks
   • Click Retry

Account Issues

Can't Log In

Solutions:

1. Reset password:

   • Click "Forgot password" on login page
   • Check email for reset link

2. Check email address:

   • Verify you're using the correct email
   • Accounts are case-sensitive

3. Clear browser data:

   • Clear cookies and cache
   • Try incognito mode

Team Member Can't Access

Solutions:

1. Verify invitation:

   • Check they received the invite email
   • Resend invitation from Settings → Team

2. Check organization:

   • They might be in a different organization
   • Verify they're viewing the right workspace

3. Review permissions:

   • Check their role has appropriate access
   • Adjust role in Team settings

Getting More Help

If you can't resolve your issue:

1. Gather information:

   • Error messages (exact text)
   • Steps to reproduce
   • Timestamps of when issues occur
   • Sync job IDs

2. Check system status:

   • FluxCascade Status Page
   • Check if known issues are affecting you

3. Contact support:

   • Email: support@fluxcascade.com
   • Include gathered information
   • We typically respond within 24 hours

See also:

• FAQ – Common questions answered
• Error Handling – Detailed error guide
• Support – Contact options