Lỗi thường gặp

2 máy không pair được

Windows Defender đôi khi không tự allow Syncthing. Mở port manually:

# Run as Administrator
New-NetFirewallRule -DisplayName "Syncthing TCP" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 22000
New-NetFirewallRule -DisplayName "Syncthing UDP Discovery" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 21027
New-NetFirewallRule -DisplayName "Syncthing QUIC" -Direction Inbound -Action Allow -Protocol UDP -LocalPort 22000

2 máy phải reach nhau. Test:

# Trên máy A, ping IP máy B
ping &lt;MAY_B_IP&gt;

Nếu fail → máy A và B không cùng LAN, cần fix router config hoặc dùng relay servers (default Syncthing).

Web UI → check biểu tượng “Discovery” — nếu đỏ:

# Check internet connectivity
ping discovery.syncthing.net

Workaround: paste static IP của peer thay vì rely on discovery:

Add Remote Device → Advanced → Addresses: tcp://192.168.1.14:22000

Pair OK nhưng folder không đồng bộ

Cả 2 máy phải:

Folder ID trùng nhau
Sharing tab tick checkbox device kia

Verify Web UI → folder card → click “Edit” → tab Sharing → confirm.

# Verify path tồn tại + writable
Test-Path "C:\path\to\folder"
# Nếu False → tạo folder trước
New-Item -ItemType Directory "C:\path\to\folder" -Force

Permission issue: folder path phải user current có quyền write.

Conflict đồng bộ — file `.sync-conflict-`

Khi 2 máy edit cùng file lúc 1 máy offline:

hello.txt
hello.sync-conflict-20260502-150000-AMZHVWU.txt    ← from device AMZHVWU (Laptop)

Resolve manually:

Mở cả 2 versions, compare nội dung

Quyết bản đúng:

# Vd nếu bản .sync-conflict-* đúng:
Move-Item "hello.sync-conflict-*.txt" "hello.txt" -Force

Hoặc merge nội dung từ cả 2

Avoid conflicts:

Đóng app trước khi switch máy
Đợi 30s sync xong rồi mới mở máy kia

Vấn đề OAuth token / `.credentials.json`

Sau sync ~/.claude/.credentials.json 2 máy:

Login fail trên máy mới
2 máy login conflict

OAuth token có thể expire. Workaround:

# Re-login Claude Code trên máy đang fail
claude logout
claude login

Sau login, .credentials.json mới được sync về máy còn lại.

Nếu 2 máy đồng thời refresh token → 1 invalidate. Mitigation:

Chỉ login 1 máy at a time
Hoặc: chấp nhận re-login đôi khi
Hoặc: KHÔNG sync .credentials.json (add vào ignore patterns)

File “Out of Sync” mãi không hết

Folder card hiển thị X items “Out of Sync” mãi không clear:

# Check Syncthing log
tail -f ~/.config/syncthing/syncthing.log    # Linux
# Windows: %APPDATA%\Syncthing\syncthing.log

# Common error: "permission denied" — file write protected
chmod -R u+w ~/path/to/folder    # Linux
icacls "C:\path" /grant "$env:USERNAME:F" /T    # Windows

App đang mở file → lock. Đóng app, đợi 60s scan tự retry.

Common offenders:

IDE editing file (VSCode, IntelliJ)
Office docs
Database files
Antigravity .jsonl (Claude conversations)

Windows không allow chars < > : " / \ | ? * trong filename. Linux thì OK.

# Find files với illegal chars (Linux side)
find ~/path -name "*[<>:|?*]*" -type f

→ Rename hoặc add vào ignore patterns.

Syncthing daemon dừng / crash

# Check process
ps aux | grep syncthing    # Linux
tasklist | findstr syncthing    # Windows

# Restart
pkill -f syncthing && nohup syncthing serve --no-browser &    # Linux
# Windows: kill task + start lại syncthing.exe

Auto-restart on crash — Linux setup:

# Use systemd user service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/syncthing.service << 'EOF'
[Unit]
Description=Syncthing
After=network.target

[Service]
ExecStart=/usr/bin/syncthing serve --no-browser
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now syncthing

Không truy cập được Web UI

Cần access từ network khác:

Edit config.xml: change <address>127.0.0.1:8384</address> → 0.0.0.0:8384
Set GUI password (Web UI → Settings → User & Password)
Restart daemon

⚠ Security: open Web UI ra LAN cần password mạnh.

Bước tiếp theo

Performance — slow sync optimization
Architecture — design rationale