Common Errors and Root Cause

Most Syncthing problems fall into a handful of categories: permissions, network, certificate mismatches, and configuration issues. This lesson provides root-cause playbooks for each.

Learning Focus

Always start troubleshooting with the journal log and the GUI Events tab — they contain the exact error message with a timestamp that points directly to the root cause.

Diagnostic First Steps

diagnose-first.sh
# 1. Check service status
systemctl --user status syncthing

# 2. View recent logs
journalctl --user -u syncthing -n 100 --no-pager

# 3. Check API health
curl -fs -H "X-API-Key: $(grep -oPm1 '(?<=<apiKey>)[^<]+' ~/.local/share/syncthing/config.xml)" \
  https://localhost:8384/rest/system/ping \
  --cacert ~/.local/share/syncthing/https-cert.pem

# 4. List all folder states
curl -fs -H "X-API-Key: $ST_KEY" https://localhost:8384/rest/config/folders \
  --cacert ~/.local/share/syncthing/https-cert.pem | jq '.[] | {id:.id, state}'

Error Reference Matrix

Permission Errors

ERROR: [...] open /var/www/html/docs/file.txt: permission denied

Cause	Fix
Syncthing user doesn't own the sync directory	`sudo chown -R syncthing:syncthing /var/www/html/docs`
Directory has wrong permissions	`sudo chmod -R 750 /var/www/html/docs`
SELinux / AppArmor blocking Syncthing	Check `ausearch -m avc -ts today` or `aa-status`

fix-permissions.sh
# Fix ownership for the syncthing system user
sudo chown -R syncthing:syncthing /var/www/html/docs
sudo chmod -R 770 /var/www/html/docs

# For user service (running as your own user)
sudo chown -R $USER:$USER ~/SyncedFolders/

Folder Marker Missing

ERROR: folder "docs-sync": folder marker missing (this indicates potential data loss on the device)

This error means Syncthing cannot find the .stfolder sentinel file. Syncthing creates this file to confirm the root of the sync directory is mounted and accessible.

fix-folder-marker.sh
# The folder marker was deleted or the mount is missing
ls -la /var/www/html/docs/.stfolder

# Re-create the marker (only if you're certain the folder and data are correct)
touch /var/www/html/docs/.stfolder

# If using a removable drive or NFS mount — ensure it is mounted BEFORE Syncthing starts
# Add to /etc/fstab or a systemd mount unit with `RequiresMountsFor=`

warning

Never create .stfolder on an unmounted or empty directory. Syncthing will treat it as the sync root and may propagate deletions if files appear to be missing.

Certificate Mismatch

ERROR: [...] tls: failed to verify certificate: x509: certificate signed by unknown authority

Cause	Fix
Cert was regenerated — peers still have the old Device ID	Regenerate cert, share new Device ID, re-accept on all peers
GUI HTTPS cert different from sync TLS cert	Normal — they are separate; accept the GUI cert exception in the browser
SSH tunnel pointing to wrong port	Ensure tunnel forwards to `8384`, not `22000`

Device Not Connecting

INFO: Connecting to K3X2R... (no connection established)

Systematic check:

diagnose-connection.sh
# 1. Is Syncthing running on the remote?
ssh user@remote-vps "systemctl --user is-active syncthing"

# 2. Is port 22000 open?
nc -zv remote-vps-ip 22000

# 3. Check the remote firewall
ssh user@remote-vps "sudo ufw status | grep 22000"

# 4. Verify both devices have each other's Device IDs
grep -A3 "device " ~/.local/share/syncthing/config.xml | grep id=

# 5. Force set a static address (bypasses discovery)
# In config.xml, under <device>:
# <address>tcp://REMOTE-IP:22000</address>

Folder in Error State

ERROR: folder "docs-sync" cannot start: [...] insufficient free space

fix-folder-error.sh
# Check disk usage
df -h /var/www/html/docs

# Check the minimum free space setting (default: 1%)
grep -A5 "docs-sync" ~/.local/share/syncthing/config.xml | grep minFreeBytes

# Increase free space or reduce the minFreeBytes threshold
# In config.xml:
# <minFreeBytes>100000000</minFreeBytes>   <!-- 100 MB minimum -->

# After fixing, restart to clear the error state
systemctl --user restart syncthing

"Out of Sync" — Files Not Propagating

Folder "docs-sync": 3 files, 1.2 MiB out of sync with remote

See Out-of-Sync Items Debugging for a full playbook. Quick checks:

quick-sync-check.sh
# 1. Check if folder is paused
curl -fs -H "X-API-Key: $ST_KEY" \
  "https://localhost:8384/rest/db/status?folder=docs-sync" \
  --cacert ~/.local/share/syncthing/https-cert.pem | jq '.paused'

# 2. Trigger a manual rescan
curl -fs -X POST -H "X-API-Key: $ST_KEY" \
  "https://localhost:8384/rest/db/scan?folder=docs-sync" \
  --cacert ~/.local/share/syncthing/https-cert.pem

# 3. Check ignore rules are not accidentally excluding the file
cat /var/www/html/docs/.stignore

Common Mistakes Quick Reference

Error Pattern	Root Cause	Single-Line Fix
`permission denied`	Wrong ownership	`chown -R syncthing: /path`
`folder marker missing`	`.stfolder` deleted or mount missing	`touch /path/.stfolder` or fix mount
`certificate ... unknown authority`	Cert regenerated	Re-share Device ID with all peers
`no connection established`	Firewall or wrong Device ID	Check port 22000 + verify Device ID
`insufficient free space`	Disk full or minFreeBytes too high	Free disk or lower threshold in config
`configuration file is not writable`	config.xml permissions	`chown syncthing ~/.local/share/syncthing/config.xml`

Diagnostic First Steps​

Error Reference Matrix​

Permission Errors​

Folder Marker Missing​

Certificate Mismatch​

Device Not Connecting​

Folder in Error State​

"Out of Sync" — Files Not Propagating​

Common Mistakes Quick Reference​

What's Next​