Get Started
Core concepts
SDK Reference
Troubleshooting
Who's using PocketSync
Troubleshooting
Common issues, error codes, and solutions for PocketSync
Common issues and solutions
Connection issues
Symptoms:
- PocketSync initializes without errors
- No sync operations occur
Possible causes:
- Sync not started
- No user ID set
- No tables configured for sync
- No data changes detected
Solutions:
- Verify that
PocketSync.instance.start()was called - Make sure
setUserIdwas called before starting sync
Symptoms:
- Sync operations fail with network errors
- App shows offline status even when online
Possible causes:
- Invalid server URL
- Network connectivity issues
- Server is down or unreachable
Solutions:
- 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
Symptoms:
- Sync operations fail with 401 or 403 errors
- Cannot initialize PocketSync
Possible causes:
- Invalid or expired auth token
- Invalid project ID
- User ID not set before starting sync
Solutions:
- 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
Symptoms:
- PocketSync initializes without errors
- No data is synchronized between devices
Possible causes:
- Incorrect table configuration
- Data doesn’t meet sync criteria
- Sync process is stopped or paused
Solutions:
- 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
Symptoms:
- Unexpected data values after sync
- Different data appears on different devices
Possible causes:
- Conflict resolution strategy not appropriate for your use case
- Custom resolver function has bugs
Solutions:
- 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
Symptoms:
- Records disappear after sync
- Fields are reset to default values
Possible causes:
- Improper conflict resolution
- Database schema mismatch
- Incorrect data types
Solutions:
- Verify schema consistency across devices
- Check for proper data type handling
- Implement a custom conflict resolver that preserves data
- Restore from backup if available
Symptoms:
- Sync operations take a long time
- High battery or network usage
Possible causes:
- Large dataset
- Frequent changes triggering many sync operations
- Inefficient change tracking
Solutions:
- 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:
final options = PocketSyncOptions(
// ... other options
verbose: true,
);
Inspect database
Directly inspect the database to verify data integrity:
final db = PocketSync.instance.database;
final records = await db.query('your_table');
print('Records: $records');
Frequently asked questions
If you need to reset the sync state, you can use the resetChangeTracking method:
await PocketSync.instance.resetChangeTracking();
This will clear all pending changes and reset the sync state. Note that this won’t delete your data, just the sync metadata.
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
For very long offline periods (weeks/months), you might want to consider a full resync by calling resetChangeTracking() followed by start().
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
You can also implement a simple UI indicator to show sync status to users.
Yes, you can configure which tables to sync when initializing PocketSync:
final databaseOptions = PocketSyncDatabaseOptions(
tables: [
TableDefinition(
name: 'todos',
syncEnabled: true,
// other options
),
TableDefinition(
name: 'settings',
syncEnabled: false, // This table won't sync
// other options
),
],
);
For more granular control, you can implement custom logic to determine which records to sync.
When changing your database schema:
- Update your table definitions
- Increment your database version
- Provide migration scripts
final databaseOptions = PocketSyncDatabaseOptions(
version: 2, // Increment this when schema changes
onUpgrade: (db, oldVersion, newVersion) async {
if (oldVersion == 1 && newVersion == 2) {
await db.execute('ALTER TABLE todos ADD COLUMN priority INTEGER');
}
},
// other options
);
Always test migrations thoroughly before deploying to production.
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