How to Troubleshoot Common FNFSync ProblemsFNFSync is a file synchronization tool used to keep folders and files consistent across devices or servers. Like any synchronization software, it can run into issues caused by configuration mistakes, network problems, permission errors, or bugs. This article walks through common FNFSync problems, systematic troubleshooting steps, and practical fixes so you can restore reliable sync quickly.
1. Preparation: gather diagnostic information
Before changing settings or running fixes, collect information so you can identify the root cause and, if needed, revert steps.
- Check FNFSync version: run the command-line or app About section to note the exact version.
- Note operating system and version on each endpoint (Windows, macOS, Linux).
- Record recent changes: updates, configuration edits, new files, or network changes.
- Locate FNFSync log files (common paths: /var/log/fnfsync, ~/.fnfsync/logs, or application-specific directories) and open the most recent entries.
- Identify error messages displayed in the UI or logs; copy full messages (timestamps included).
2. Sync not starting or scheduled jobs not running
Symptoms: sync never begins, scheduled syncs don’t execute.
Common causes:
- FNFSync daemon/service not running.
- Scheduler misconfiguration or disabled.
- Corrupted local database or lock file.
- Permissions preventing process startup.
Steps to fix:
- Confirm FNFSync service status:
- Linux/macOS: systemctl status fnfsync or ps aux | grep fnfsync
- Windows: check Services (services.msc) or Task Manager > Services
- Start/restart the service:
- systemctl restart fnfsync (Linux)
- Use the Windows Services UI or sc start/stop
- Review scheduler configuration in settings (time, recurrence, time zone).
- Inspect and rotate local DB or lock files:
- Move or rename the local DB (e.g., fnfsync.db → fnfsync.db.bak) to force recreation (backup first).
- Check file and directory permissions for FNFSync runtime user; ensure it can read config files and write to its data directory.
3. Files not syncing or missing changes
Symptoms: some files are not transferred, or changes on one side don’t appear on others.
Common causes:
- Exclude/include filters preventing files from being processed.
- File size or type limits.
- Timestamp or clock skew causing conflict detection issues.
- Network interruption mid-transfer.
- Insufficient disk space on target.
Steps to fix:
- Review include/exclude rules — ensure your file patterns aren’t accidentally excluding files (wildcards, regex).
- Check size/type limits in FNFSync settings; raise limits if necessary.
- Verify clocks on all devices; keep them synchronized (e.g., use NTP). Significant clock drift can prevent proper change detection.
- Inspect transfer logs for partial transfer errors. If transfers are interrupted, re-run sync or enable resume options.
- Confirm free disk space on all endpoints.
- Force a re-scan or re-index in settings to refresh file metadata, then run a full sync.
4. Conflicts and duplicate files
Symptoms: FNFSync creates .conflict, .duplicate, or timestamped copies; users end up with multiple versions.
Common causes:
- Concurrent edits on different endpoints.
- Inconsistent conflict-resolution policy (e.g., “keep local” vs “keep newest”).
- Timezone or clock differences.
How to resolve:
- Decide on a conflict-resolution policy and set it globally (prefer newest, prefer server, prompt).
- For existing conflicts, choose the desired version and delete other duplicates. Many FNFSync clients offer a conflict resolution UI.
- Fix clock drift to reduce false conflicts (use NTP).
- Consider locking or check-out features if frequent concurrent edits occur (if FNFSync supports file locking).
5. Permission and ownership errors
Symptoms: “Permission denied”, “access denied”, or inability to write files at the destination.
Common causes:
- FNFSync process running under an account lacking rights.
- Files created with restrictive permissions preventing overwrites.
- Different user/UID maps across Unix systems.
Fixes:
- Run FNFSync under a user with appropriate read/write permissions for source and destination directories.
- Adjust file and folder permissions (chmod/chown on Unix, Security tab on Windows) to allow the sync user to modify files.
- If syncing between systems with different UID/GID, enable UID/GID mapping in FNFSync or use a shared identity mapping mechanism.
- For network shares, ensure the network service account has rights to the share and that mount options allow writes.
6. Network issues and slow transfers
Symptoms: very slow syncs, frequent timeouts, or dropped connections.
Common causes:
- High latency or low bandwidth.
- Firewall or NAT interfering with connections.
- VPN or proxy misconfiguration.
- Unstable Wi‑Fi.
Troubleshooting steps:
- Test raw network throughput between endpoints (ping, traceroute, iperf).
- Check whether firewalls block FNFSync ports or protocols; open/forward necessary ports.
- If using VPN/proxy, verify settings and route traffic correctly.
- Limit concurrency or throttle settings in FNFSync to reduce connection strain.
- Use wired connections for large initial syncs or set up an offline transfer for huge datasets (seed via external drive).
7. Corrupted local database or index
Symptoms: repeated errors referencing the local DB, failed scans, or inconsistent state after restart.
Causes:
- Abrupt shutdown during DB write.
- Disk errors or filesystem corruption.
Recovery steps:
- Stop FNFSync service.
- Back up the current database file(s).
- Delete or move the corrupted DB so FNFSync can rebuild it on next start.
- Start FNFSync and allow a full re-scan; this may take time for large datasets.
- If disk errors are suspected, run filesystem checks (fsck/chkdsk) and fix disk issues first.
8. Error codes and log messages — how to interpret them
Approach:
- Search logs for the earliest error around the time of the incident; subsequent errors often follow the first.
- Note recurring error codes and match them to FNFSync documentation or release notes.
- Pay attention to stack traces or module names in logs; they point to components (network, db, scanner).
Example common log entries and meaning:
- “E_CONN_TIMEOUT”: connection timed out — check network/firewall.
- “E_DB_LOCK”: database locked — another process or stale lock; stop service and remove lock.
- “E_PERM_DENIED”: permission denied — adjust user rights or file permissions.
9. Upgrades, patches, and compatibility
Best practices:
- Keep FNFSync updated, but read release notes for breaking changes before upgrading.
- Test upgrades in a staging environment for critical setups.
- After upgrading, re-run a full sync to ensure indexes and metadata are consistent.
When to roll back:
- If a new version introduces regression causing data loss or major failures, restore from backups and revert to a known-good version while reporting the issue.
10. When to escalate: support and reproducible reports
If you can’t fix the problem, prepare a clear, reproducible report for FNFSync support:
Include:
- FNFSync version and platform.
- Exact steps to reproduce.
- Relevant log excerpts (redact any sensitive info).
- Config files (sync rules, exclude/include patterns).
- Network environment (NAT, VPN, firewall).
- Timestamps and affected file examples.
11. Preventative maintenance
- Schedule periodic full re-scans and integrity checks.
- Monitor disk usage and rotate logs.
- Use versioned backups before major changes.
- Keep system clocks synced and maintain reliable networking.
- Document custom exclude/include rules and share them with your team.
Summary
- Start by gathering logs and version info.
- Check service status, permissions, and include/exclude rules.
- Fix clock drift, disk space, and network/firewall issues.
- Rebuild local DB when corrupted and choose a consistent conflict policy.
- Escalate with concise reproducible reports if needed.
Leave a Reply