{"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/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/codex-legacy-sync.js#L10-L46","documentation":"openRegularFileNoFollow safely opens legacy Codex sync files, refusing anything that is not a plain regular file. When an open fails with ENOENT, it lstats the path: if the path actually resolves to a symlink or non-regular file (a race where it vanished/reappeared, or the open failed for another reason), it throws this error instead of proceeding. It protects against managing or overwriting links and special files.","triggerScenarios":"Running install/rollback/uninstall legacy Codex sync when the target path (e.g. ~/.codex config file) is a symlink to elsewhere, a FIFO/device/directory, or turns into one between the failed open and the lstat check (TOCTOU).","commonSituations":"Users symlink their dotfiles (e.g. ~/.codex/config.toml -> ~/dotfiles/config.toml) into a dotfiles repo; container images placing sockets or special files at the path; partially deleted sync state.","solutions":["Replace the symlink/special file at the path with a real regular file (cp --remove-destination the target content to a plain file).","Re-run the sync/uninstall command after the path is a regular file.","If you intentionally symlink dotfiles, exclude that path from legacy Codex sync or manage it yourself outside this tool.","Inspect the path: ls -la ~/.codex/... to confirm what is there before retrying."],"exampleFix":"// before\nln -s ~/dotfiles/codex-config.toml ~/.codex/config.toml   # sync refuses\n// after\nrm ~/.codex/config.toml && cp ~/dotfiles/codex-config.toml ~/.codex/config.toml","handlingStrategy":"validation","validationCode":"const fs = require('fs');\nconst st = fs.lstatSync(targetPath); // throws ENOENT if absent (fine)\nif (st.isSymbolicLink() || !st.isFile()) throw new Error(`Path must be a regular file: ${targetPath}`);","typeGuard":"function isRegularFileSync(p) { try { const st = require('fs').lstatSync(p); return st.isFile() && !st.isSymbolicLink(); } catch { return false; } }","tryCatchPattern":"try { await uninstallLegacyCodexSync(); } catch (e) { if (e.message.startsWith('Refusing to manage non-regular')) { console.error('Replace the symlink/special file with a plain file, then retry'); } else throw e; }","preventionTips":["Don't symlink files managed by legacy Codex sync (e.g. ~/.codex configs) into dotfile repos","Run ls -la on target paths when sync unexpectedly fails","Keep sync targets on plain local filesystems, not sockets/devices"],"tags":["security","filesystem","symlink"],"backgroundTag":"incompatible-source-type","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}