Syncthing 'The device is not ready': 드라이브·마운트 점검

The device is not ready 오류에서 먼저 확인할 것

이 메시지만으로 disk 고장이나 원격 Syncthing 장치의 offline 상태를 단정하지 않습니다. 설정된 folder 경로가 실제 데이터 volume을 가리키는지 먼저 확인합니다. drive·mount가 빠졌다면 올바른 storage를 복원하고 예상 파일이 돌아온 뒤 동기화를 재개합니다. 빈 경로에 marker를 만들어 오류만 없애면 삭제가 전파될 수 있습니다.

Marker Name을 별도로 지정한 폴더는 기본 .stfolder 대신 실제 설정된 marker를 확인합니다. 아래 marker 조회 명령은 기본 이름을 쓰므로 사용자 지정인 경우 확인된 이름으로 바꿉니다. storage와 데이터가 정상인데 marker만 없을 때의 복구 조건은 아래에서 따로 다룹니다.

복구 작업 전: 영향받은 폴더를 Syncthing UI에서 Pause하고 설정과 데이터를 백업합니다. mount나 marker가 돌아오는 즉시 자동 동기화가 재개되지 않게 유지한 뒤 실제 볼륨과 예상 데이터를 대조하세요.

marker를 만들기 전에 storage가 맞는지 확인한다

Syncthing은 folder root의 기본 .stfolder marker가 사라지면 동기화를 멈춥니다. 공식 FAQ는 mount가 빠진 상태에서 빈 mount point를 정상 폴더로 오인해 원격 파일 삭제를 전파하는 일을 막기 위한 동작이라고 설명합니다. 따라서 오류를 없애려고 빈 디렉터리에 marker부터 다시 만들면 보호 장치를 우회할 수 있습니다.

Windows의 The device is not ready는 drive가 준비되지 않았거나 경로가 실제 volume을 가리키지 않을 때 나타날 수 있습니다. Linux와 NAS에서는 mount 실패 뒤 비어 있는 mount point만 남아 같은 표면 증상을 만들 수 있습니다. 어느 환경이든 폴더 안의 예상 데이터와 volume identity를 먼저 확인합니다.

재개 전에 확인할 세 가지 일치 조건

조건	확인 내용	불일치 시 조치
storage identity	drive label, volume, filesystem, mount source	올바른 device를 먼저 mount합니다.
folder contents	예상 파일과 디렉터리가 존재	빈 mount point에서 동기화를 재개하지 않습니다.
folder marker	root에 정확한 `.stfolder` 존재	storage가 맞을 때만 marker 복구를 검토합니다.

Windows drive 점검

$folder = 'E:\Sync'
Get-Volume
Test-Path $folder
Get-ChildItem $folder -Force | Select-Object -First 20 Name,Length,LastWriteTime
Get-Item (Join-Path $folder '.stfolder') -Force -ErrorAction SilentlyContinue

drive letter는 removable storage 재연결 뒤 달라질 수 있습니다. label과 filesystem을 이전 기록과 비교하고, E:\Sync가 실제 데이터 volume인지 확인합니다. 처음 보는 빈 폴더라면 marker를 만들지 않고 Windows Disk Management와 cable 또는 enclosure 상태부터 확인합니다.

Linux와 NAS mount 점검

findmnt -T /volume1/sync
df -T /volume1/sync
ls -la /volume1/sync | head -n 20
stat /volume1/sync/.stfolder

findmnt가 parent filesystem만 보여 주거나 예상한 source가 아니면 service를 재개하지 않습니다. NAS package 또는 container에서 Syncthing을 실행한다면 host mount와 container bind mount를 둘 다 확인해야 합니다. container 안에 경로가 보여도 host에서 잘못된 빈 디렉터리를 bind했을 수 있습니다.

실행해 본 사전 점검: marker가 있어도 잘못된 빈 경로는 통과시키지 않기

2026-10-22 Ubuntu 24.04의 임시 디렉터리에서 아래 Python 3 코드를 실행했습니다. Syncthing이나 실제 동기화 폴더는 건드리지 않았습니다. 코드를 path-preflight.py로 저장하고, 경로·실제 Marker Name·정상 볼륨에 있어야 할 파일의 상대 경로를 인자로 줍니다. 파일을 최대 1바이트 읽고 존재 조건을 출력하며 파일·설정·marker를 만들거나 바꾸지 않습니다.

from pathlib import Path
import json
import sys

root = Path(sys.argv[1])
marker = sys.argv[2]        # Actual Marker Name from folder settings
known_file = sys.argv[3]    # A file known to exist on the correct volume
checks = {
    "root_directory": root.is_dir(),
    "configured_marker": (root / marker).exists(),
    "known_file_readable": False,
}
try:
    with (root / known_file).open("rb") as stream:
        stream.read(1)
    checks["known_file_readable"] = True
except OSError:
    pass
print(json.dumps(checks, sort_keys=True))
sys.exit(0 if all(checks.values()) else 2)

python3 path-preflight.py /path/to/sync .stfolder known-file.txt

임시 디렉터리 조건	실제 확인 결과	종료 코드
정상 root + 기본 marker + 기준 파일	모두 true	0
빈 경로 + marker 없음	marker·기준 파일 false	2
빈 경로 + marker만 있음	기준 파일 false	2
정상 root + 사용자 지정 marker + 기준 파일	모두 true	0

종료 코드 0은 동기화 재개 승인이나 올바른 볼륨의 증명이 아닙니다. 잘못 복제된 디렉터리에도 같은 파일이 있을 수 있습니다. 위 Linux의 findmnt 또는 Windows의 volume 정보를 이전 기록과 따로 대조하고, 가능한 경우 실제 Syncthing 서비스 사용자 권한으로 조회합니다. 운영 폴더에는 marker를 새로 만들지 않은 채 먼저 확인하세요.

세 번째 결과는 marker만 검사하면 놓치는 경우를 보여 줍니다. 이 실험은 경로 점검 코드의 동작만 확인했으며, Windows의 장치 오류·실제 mount 장애·Syncthing의 삭제 전파나 복구 성공은 재현하지 않았습니다. 기준 파일 하나로 전체 데이터의 완전성을 판단할 수도 없습니다.

상태별 복구 선택

storage가 unmount됨: 원래 device를 같은 경로에 mount하고 데이터가 맞는지 확인합니다. marker를 새로 만들 필요가 없는 경우가 대부분입니다.
폴더가 다른 경로로 이동됨: 원래 경로로 돌리거나 Syncthing 설정에서 새 경로로 폴더를 다시 구성합니다. 실행 중 config.xml을 임의 편집하지 않습니다.
데이터는 맞고 marker만 없음: cleaner가 빈 marker 디렉터리를 제거했는지 확인합니다. 공식 FAQ가 설명하는 방식으로 marker를 복구하되, 먼저 폴더가 완전한지 점검합니다.
경로가 비어 있고 원래 storage를 찾을 수 없음: 동기화를 재개하지 않습니다. 원격 device에서 발생한 변경도 멈추고 backup과 storage 복구를 우선합니다.
권한 때문에 marker를 읽지 못함: Syncthing service가 실행되는 실제 사용자와 mount 권한을 확인합니다. 무조건 재귀 chown으로 공유 데이터 전체를 바꾸지 않습니다.

폴더 삭제 후 재추가의 의미

공식 FAQ는 확신이 없을 때 UI에서 폴더를 제거하고 같은 위치에 다시 추가하면 marker와 database state를 새로 만들 수 있다고 설명합니다. 하지만 이 작업은 기존 folder database state를 reset하고 폴더를 새 폴더처럼 취급합니다. remote와 local 내용이 합쳐질 때 어느 변경이 이길지 사전에 검토해야 합니다.

재추가 전에는 folder ID, type, shared devices, versioning, ignore pattern, path를 기록합니다. send only 또는 receive only 같은 folder type을 기본 send receive로 잘못 재생성하면 복구 절차가 데이터 정책을 바꿀 수 있습니다.

검증과 롤백

올바른 storage와 marker가 확인된 뒤 folder를 resume하고, 처음 scan에서 local additions와 deletions 수를 확인합니다. 예상하지 못한 대량 삭제가 보이면 즉시 pause하고 경로를 다시 점검합니다. remote device 하나만 보고 완료로 판단하지 말고 folder를 공유하는 모든 device의 상태를 비교합니다.

잘못된 경로로 재추가했다면 동기화를 중단하고 잘못 만든 folder entry를 제거한 뒤 원래 설정 기록으로 돌아갑니다. versioning folder와 backup을 먼저 확인하고, remote에 전파된 삭제를 단순 rescan으로 복구된다고 가정하지 않습니다.

같이 확인할 글

공식 문서 및 확인 기준

Syncthing FAQ – missing folder marker, unmounted storage와 폴더 재추가의 영향
Syncthing GUI guide – folder path와 missing marker 상태
Syncthing configuration – folder path, config 위치와 folder 설정 범위
Syncthing database status endpoint – scan과 local state를 확인할 공식 API

이 글에 남아 있던 이전 검증 기록

검증 수준: 공식 문서 대조

Syncthing의 missing marker 보호 동작과 재추가 영향을 공식 문서로 확인했습니다. 특정 storage failure는 재현하지 않았으므로 drive 또는 filesystem 고장 원인을 추정하지 않습니다.

작성 방식과 수정 정책 · 오류 제보