{"record":{"id":"dc96e7b137a767cc","repo":"caddyserver/caddy","slug":"syncing-downloaded-file-to-device-v","errorCode":null,"errorMessage":"syncing downloaded file to device: %v","messagePattern":"syncing downloaded file to device: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/packagesfuncs.go","lineNumber":336,"sourceCode":"\nfunc writeCaddyBinary(path string, body *io.ReadCloser, fileInfo os.FileInfo) error {\n\tl := caddy.Log()\n\tdestFile, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_TRUNC, fileInfo.Mode())\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to open destination file: %v\", err)\n\t}\n\tdefer destFile.Close()\n\n\tl.Info(\"downloading binary\", zap.String(\"destination\", path))\n\n\t_, err = io.Copy(destFile, *body)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to download file: %v\", err)\n\t}\n\n\terr = destFile.Sync()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"syncing downloaded file to device: %v\", err)\n\t}\n\n\treturn nil\n}\n\nconst downloadPath = \"https://caddyserver.com/api/download\"\n\ntype pluginPackage struct {\n\tVersion string\n\tPath    string\n}\n\nfunc (p pluginPackage) String() string {\n\tif p.Version == \"\" {\n\t\treturn p.Path\n\t}\n\treturn p.Path + \"@\" + p.Version\n}","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/cmd/packagesfuncs.go#L318-L354","documentation":"After the bytes are written, destFile.Sync() (fsync) fails, meaning the OS could not flush the downloaded binary to stable storage. This signals hardware/filesystem trouble: I/O errors, device full, or the file living on failing storage. The deferred restore brings back the original binary.","triggerScenarios":"Disk full exactly at fsync time; failing disk or NFS mount erroring on flush; loop-device/container overlay issues; USB media removed.","commonSituations":"Small root partitions filling during the ~40MB write; flaky network-attached storage holding /usr/local/bin; failing SSD returning EIO.","solutions":["Check disk health and space: df -h on the binary's mount, dmesg | grep -i 'i/o error'","Free space and retry the upgrade","If storage is genuinely failing, replace it before attempting any upgrade","Move the binary to reliable local storage and re-run"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"df -h \"$(dirname \"$(command -v caddy)\")\"   # confirm free space before upgrading","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep at least a few hundred MB free on the binary's filesystem","Investigate dmesg I/O errors before trusting upgrades on failing disks","Avoid placing the binary on flaky network storage"],"tags":["filesystem","disk","upgrade"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}