{"record":{"id":"516d220a514c579c","repo":"affaan-m/ECC","slug":"refusing-to-create-non-regular-legacy-sync-path","errorCode":null,"errorMessage":"Refusing to create non-regular legacy sync path: ${filePath}","messagePattern":"Refusing to create non-regular legacy sync path: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/codex-legacy-sync.js","lineNumber":95,"sourceCode":"  }\n}\n\nfunction replaceOpenedRegularFile(opened, content, mode = null) {\n  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);\n  fs.ftruncateSync(opened.descriptor, 0);\n  fs.writeSync(opened.descriptor, buffer, 0, buffer.length, 0);\n  if (mode) fs.fchmodSync(opened.descriptor, mode);\n  fs.fsyncSync(opened.descriptor);\n}\n\nfunction createRegularFileNoFollow(filePath, content, mode = 0o600) {\n  const noFollow = fs.constants.O_NOFOLLOW || 0;\n  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow;\n  const descriptor = fs.openSync(filePath, flags, mode);\n  try {\n    const stat = fs.fstatSync(descriptor);\n    if (!stat.isFile()) {\n      throw new Error(`Refusing to create non-regular legacy sync path: ${filePath}`);\n    }\n    fs.writeFileSync(descriptor, content);\n    fs.fchmodSync(descriptor, mode);\n    fs.fsyncSync(descriptor);\n  } finally {\n    fs.closeSync(descriptor);\n  }\n}\n\nfunction removeOpenedRegularFile(filePath, opened) {\n  const quarantineDir = fs.mkdtempSync(path.join(path.dirname(filePath), '.ecc-remove-'));\n  const quarantinePath = path.join(quarantineDir, path.basename(filePath));\n  fs.renameSync(filePath, quarantinePath);\n  const quarantined = openRegularFileNoFollow(quarantinePath);\n  const openedStat = fs.fstatSync(opened.descriptor, { bigint: true });\n  const quarantinedStat = fs.fstatSync(quarantined.descriptor, { bigint: true });\n  fs.closeSync(quarantined.descriptor);\n  fs.closeSync(opened.descriptor);","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/lib/codex-legacy-sync.js#L77-L113","documentation":"createRegularFileNoFollow creates the state file with O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW and then requires fstat on the fresh descriptor to report a regular file. O_EXCL guarantees the path did not exist before, so reaching a non-regular stat means the filesystem handed back something unexpected — an exotic/FUSE mount that does not behave like a normal directory tree, or the just-created entry being swapped for a special file in the same instant.","triggerScenarios":"The Codex state directory lives on a FUSE/network/virtual filesystem whose O_EXCL creates resolve oddly; a race replaces the newly created file with a FIFO/socket before fstat.","commonSituations":"HOME or the config dir redirected onto a cloud-sync FUSE mount (Dropbox, gdrive-fs), a network share, or a container virtual filesystem; rare hostile races.","solutions":["Move the state directory onto a local POSIX filesystem (ext4/APFS/NTFS) and retry.","If the directory must be synced, exclude the live state file and sync copies instead.","Re-run after remounting the odd filesystem — if it persists, report the mount type as a bug against codex-legacy-sync."],"exampleFix":"# before: HOME on a FUSE cloud mount\n$ df -T ~/.codex\n~/.codex  fuseblk ...\n\n# after\n$ export CODEX_HOME=\"$HOME/.codex-local\"   # local fs\n$ ecc codex sync","handlingStrategy":"retry","validationCode":"import fs from 'node:fs';\nfunction assertPosixCreateDir(dir) {\n  const probe = path.join(dir, `.probe-${process.pid}`);\n  const fd = fs.openSync(probe, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);\n  try { if (!fs.fstatSync(fd).isFile()) throw new Error(`${dir} does not behave like a POSIX dir`); }\n  finally { fs.closeSync(fd); fs.unlinkSync(probe); }\n}","typeGuard":null,"tryCatchPattern":"try { createAndSync(); } catch (e) {\n  if (/Refusing to create non-regular/.test(e.message)) { throw new Error('move the state dir off FUSE/network mounts and retry'); }\n  throw e;\n}","preventionTips":["Keep the Codex/ECC state directory on a native local filesystem, not FUSE/cloud-sync mounts.","Smoke-test O_EXCL create semantics when introducing exotic mounts into $HOME."],"tags":["filesystem","fuse","codex-sync","race-condition"],"backgroundTag":"non-regular-file-refused","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}