Skip to main content

Out-of-Sync Items Debugging

"Out of sync" is the most common ambiguous state in Syncthing. It can mean a file is actively syncing, blocked by an ignore rule, locked by another process, or stuck in a conflict loop. This lesson systematically isolates each cause.

Learning Focus

Use the REST API /rest/db/need endpoint — it is the single most powerful debugging tool for out-of-sync items because it lists the exact files that need to transfer and why.

Step 1 — Identify What Is Out of Sync​

identify-oos.sh
STKEY="your-api-key"
CERT="$HOME/.local/share/syncthing/https-cert.pem"
FOLDER="docs-sync"

# Get folder sync state
curl -fs -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/status?folder=$FOLDER" \
  --cacert "$CERT" | jq '{state:.state, needFiles:.needFiles, needBytes:.needBytes, errors:.errors}'

# List the specific files that need to sync (from the perspective of a peer)
PEER_ID="PEER-DEVICE-ID-HERE"
curl -fs -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/need?folder=$FOLDER&device=$PEER_ID" \
  --cacert "$CERT" | jq '.files[] | {name:.name, modified:.modified, size:.size}'

Step 2 — Check the Error Log for That Folder​

folder-errors.sh
# Folder-specific errors (files that failed to sync)
curl -fs -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/folder/errors?folder=$FOLDER" \
  --cacert "$CERT" | jq '.errors[] | {path:.path, error:.error}'

Common error patterns and causes:

Error MessageRoot Cause
open .../file: permission deniedFile not readable/writable by Syncthing process
rename .../file: device or resource busyFile locked by another process
no space left on deviceTarget disk full
the file does not existFile was deleted during sync (race condition, usually harmless)

Step 3 — Check if File Is Ignored​

check-ignore.sh
# Test whether a specific file matches the .stignore rules
FILE_PATH="reports/q1-backup.csv"
curl -fs -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/ignores?folder=$FOLDER" \
  --cacert "$CERT" | jq --arg f "$FILE_PATH" '.ignore[] | select(. as $pat | $f | test($pat))'

# Also view the raw ignore rules
cat /var/www/html/docs/.stignore

If the file matches an ignore rule:

  1. Remove or adjust the pattern in .stignore
  2. Trigger a rescan: curl -X POST .../rest/db/scan?folder=$FOLDER

Step 4 — Check for File Locks​

check-file-lock.sh
# Find processes holding a lock on the file
LOCKED_FILE="/var/www/html/docs/reports/q1.csv"
sudo lsof "$LOCKED_FILE"
sudo fuser "$LOCKED_FILE"

# If a web server, CMS, or editor has the file open, it cannot be synced
# Wait for the process to release it, or restart the offending process

Step 5 — Check for Conflicts​

find-conflicts.sh
# List all conflict copies in the sync folder
find /var/www/html/docs -name "*.sync-conflict-*" | sort

# Also check via API
curl -fs -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/status?folder=$FOLDER" \
  --cacert "$CERT" | jq '.conflicts'

If conflicts exist, see How Syncthing Handles Conflicts for resolution steps.

Step 6 — Force a Rescan​

force-rescan.sh
# Rescan the entire folder
curl -fs -X POST \
  -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/scan?folder=$FOLDER" \
  --cacert "$CERT"

# Rescan a specific subfolder only
curl -fs -X POST \
  -H "X-API-Key: $STKEY" \
  "https://localhost:8384/rest/db/scan?folder=$FOLDER&sub=reports/" \
  --cacert "$CERT"

Step 7 — Reset the Database for a Folder (Last Resort)​

If a folder is permanently stuck and no other fix works:

reset-folder-db.sh
# Stop Syncthing first
systemctl --user stop syncthing

# Delete only the database index for this folder (not the actual files)
# The database is recreated on next startup with a full rescan
syncthing --reset-database

# Restart
systemctl --user start syncthing
# Syncthing will re-index and re-sync — may take time for large folders
warning

--reset-database deletes all folder indexes. Syncthing will perform a full rescan of all folders on startup. This can take significant time and CPU for large sync sets.

Decision Flowchart​

flowchart TD
  A[Out of sync items reported] --> B[Check /rest/db/need — which files?]
  B --> C[Check /rest/folder/errors — any errors?]
  C --> D{Error found?}
  D -- Yes: permissions --> E[Fix chown/chmod on the file]
  D -- Yes: locked --> F[Kill or wait for locking process]
  D -- Yes: disk full --> G[Free disk space]
  D -- No errors --> H[Check .stignore — is file excluded?]
  H -- Yes --> I[Update .stignore pattern]
  H -- No --> J[Check for conflicts]
  J -- Yes --> K[Resolve conflict copies]
  J -- No --> L[Force rescan via API]
  L --> M{Still stuck?}
  M -- Yes --> N[Reset database — last resort]

Common Mistakes​

MistakeSymptomFix
.stignore has overly broad patternsLegitimate files silently excludedTest each pattern with /rest/db/ignores
Backup agent locking files during syncFiles stuck in error stateSchedule backup outside peak sync windows
Syncing a path another process writes to constantlyNever reaches "idle" stateUse a staging directory + move-then-sync pattern

What's Next​