Troubleshooting
Troubleshooting
Common issues, error codes, and solutions for PocketSync
Common issues and solutions
Connection issues
Nothing happens when I start sync
Nothing happens when I start sync
Symptoms:
- PocketSync initializes without errors
- No sync operations occur
- Sync not started
- No user ID set
- No tables configured for sync
- No data changes detected
- Verify that
PocketSync.instance.start()was called - Make sure
setUserIdwas called before starting sync
Cannot connect to PocketSync server
Cannot connect to PocketSync server
Symptoms:
- Sync operations fail with network errors
- App shows offline status even when online
- Invalid server URL
- Network connectivity issues
- Server is down or unreachable
- Verify your server URL in the PocketSyncOptions
- Check your device’s network connection
- Verify that your auth token is valid
- Check the PocketSync status page for any outages
Authentication failures
Authentication failures
Symptoms:
- Sync operations fail with 401 or 403 errors
- Cannot initialize PocketSync
- Invalid or expired auth token
- Invalid project ID
- User ID not set before starting sync
- Verify your auth token and project ID in the PocketSync console
- Ensure you’ve called
setUserId()before starting sync - Check if your token has the necessary permissions
Sync starts but no data is transferred
Sync starts but no data is transferred
Symptoms:
- PocketSync initializes without errors
- No data is synchronized between devices
- Incorrect table configuration
- Data doesn’t meet sync criteria
- Sync process is stopped or paused
- Verify that your tables are properly configured for sync
- Check if
PocketSync.instance.start()was called - Inspect logs with verbose mode enabled
- Verify that data changes are being detected
Data Synchronization Issues
Data conflicts not resolving correctly
Data conflicts not resolving correctly
Symptoms:
- Unexpected data values after sync
- Different data appears on different devices
- Conflict resolution strategy not appropriate for your use case
- Custom resolver function has bugs
- Review your conflict resolution strategy
- Test your custom resolver with different conflict scenarios
- Consider using a different built-in strategy
- Enable verbose logging to see conflict details
Data loss during synchronization
Data loss during synchronization
Symptoms:
- Records disappear after sync
- Fields are reset to default values
- Improper conflict resolution
- Database schema mismatch
- Incorrect data types
- Verify schema consistency across devices
- Check for proper data type handling
- Implement a custom conflict resolver that preserves data
- Restore from backup if available
Sync is slow or consuming excessive resources
Sync is slow or consuming excessive resources
Symptoms:
- Sync operations take a long time
- High battery or network usage
- Large dataset
- Frequent changes triggering many sync operations
- Inefficient change tracking
- Adjust sync frequency and debounce settings
- Optimize database queries and change detection
- Consider syncing only essential data
- Implement data pagination or chunking for large datasets
Debugging tips
Enable verbose logging
Enable detailed logging to help diagnose issues:Inspect database
Directly inspect the database to verify data integrity:Frequently asked questions
How do I reset sync state if things go wrong?
How do I reset sync state if things go wrong?
If you need to reset the sync state, you can use the This will clear all pending changes and reset the sync state. Note that this won’t delete your data, just the sync metadata.
resetChangeTracking method:What happens if a device is offline for an extended period?
What happens if a device is offline for an extended period?
PocketSync is designed to handle extended offline periods. When a device comes back online, it will:
- Upload any local changes that occurred while offline
- Download remote changes that occurred during the offline period
- Resolve any conflicts according to your configured strategy
resetChangeTracking() followed by start().How can I verify that sync is working correctly?
How can I verify that sync is working correctly?
To verify sync is working:
- Enable verbose logging
- Make changes on one device and check that they appear on another
- Monitor the sync status using the
syncStatusstream - Check the server logs in the PocketSync console
Can I sync only specific tables or records?
Can I sync only specific tables or records?
Yes, you can configure which tables to sync when initializing PocketSync:For more granular control, you can implement custom logic to determine which records to sync.
How do I handle schema migrations with PocketSync?
How do I handle schema migrations with PocketSync?
When changing your database schema:Always test migrations thoroughly before deploying to production.
- Update your table definitions
- Increment your database version
- Provide migration scripts
Still need help?
If you’re still experiencing issues:- Check our GitHub repository for known issues
- Contact us at hello@pocketsync.dev
Report a bug
Help us improve by reporting bugs and issues you encounter