{"record":{"id":"5b5106894a403620","repo":"affaan-m/ECC","slug":"refusing-to-manage-non-regular-legacy-sync-path","errorCode":null,"errorMessage":"Refusing to manage non-regular legacy sync path: ${filePath}","messagePattern":"Refusing to manage non-regular legacy sync path: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/codex-legacy-sync.js","lineNumber":28,"sourceCode":"const BEGIN_MARKER = '<!-- BEGIN ECC -->';\nconst END_MARKER = '<!-- END ECC -->';\n\nfunction getStatePath(codexHome) {\n  return path.join(codexHome, 'ecc', 'legacy-sync-state.json');\n}\n\nfunction openRegularFileNoFollow(filePath, writable = false) {\n  const noFollow = fs.constants.O_NOFOLLOW || 0;\n  const flags = (writable ? fs.constants.O_RDWR : fs.constants.O_RDONLY) | noFollow;\n  let descriptor;\n  try {\n    descriptor = fs.openSync(filePath, flags);\n  } catch (error) {\n    if (error.code === 'ENOENT') {\n      try {\n        const unresolved = fs.lstatSync(filePath);\n        if (unresolved.isSymbolicLink() || !unresolved.isFile()) {\n          throw new Error(`Refusing to manage non-regular legacy sync path: ${filePath}`);\n        }\n      } catch (lstatError) {\n        if (lstatError.code === 'ENOENT') return null;\n        throw lstatError;\n      }\n      throw error;\n    }\n    if (error.code === 'ELOOP') {\n      throw new Error(`Refusing to manage non-regular legacy sync path: ${filePath}`);\n    }\n    throw error;\n  }\n  const descriptorStat = fs.fstatSync(descriptor, { bigint: true });\n  let finalPathStat;\n  try {\n    finalPathStat = fs.lstatSync(filePath, { bigint: true });\n  } catch (error) {\n    fs.closeSync(descriptor);","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/lib/codex-legacy-sync.js#L10-L46","documentation":"codex-legacy-sync opens the legacy sync state file with O_NOFOLLOW to refuse symlink traversal. In this branch the open failed with ENOENT, yet a follow-up lstat of the same path still resolves — and shows a symlink or a non-regular file. That combination means the final component is a symlink (typically dangling, pointing at a missing target) or a special file, and the module refuses to manage such a path rather than follow it.","triggerScenarios":"The Codex legacy sync state file was replaced by a symlink whose target does not exist (dotfile manager pointing at an unmounted cloud-sync folder), or the path is a FIFO/device.","commonSituations":"Users symlinking dotfiles into Dropbox/iCloud-driven dirs that are not mounted; cleanup tools that leave dangling symlinks behind; misconfigured stow/dotbot setups touching the ECC/Codex state path.","solutions":["Inspect the path: `ls -la <statePath>` and `readlink <statePath>` to see the symlink target.","Remove the symlink and let the sync recreate a real regular file at that path (or restore a backup of the original file).","If the target lives on an unmounted volume (cloud sync), mount it or move the state file back to local disk."],"exampleFix":"# before\n$ ls -la ~/.codex/ecc-legacy-sync.json\nlrwxrwxrwx ... -> ~/Dropbox/dotfiles/ecc-legacy-sync.json  (missing)\n\n# after\n$ rm ~/.codex/ecc-legacy-sync.json\n$ ecc codex sync   # recreates a real regular file","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nfunction assertManageableStatePath(p) {\n  let st;\n  try { st = fs.lstatSync(p); }\n  catch (e) { if (e.code === 'ENOENT') return; throw e; }\n  if (st.isSymbolicLink()) throw new Error(`refusing: ${p} is a symlink`);\n  if (!st.isFile()) throw new Error(`refusing: ${p} is not a regular file`);\n}","typeGuard":"function isRegularFileNoSymlink(p) {\n  try { const st = fs.lstatSync(p); return st.isFile() && !st.isSymbolicLink(); } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Keep sync state files on local disk as real files; exclude them from dotfile symlinking.","Before running sync, quickly audit the state dir: find <dir> -type l to catch dangling or valid symlinks."],"tags":["filesystem","symlink","security","codex-sync"],"backgroundTag":"dangling-symlink-detected","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}