{"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/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/codex-legacy-sync.js#L77-L113","documentation":"createRegularFileNoFollow creates a new file with O_CREAT|O_EXCL|O_NOFOLLOW and then fstats the descriptor to confirm it is a regular file. If the freshly created node is not a regular file, the creation raced with something that substituted a non-regular object at the path (or an unusual filesystem returned an unexpected node), so the library refuses to write content into it and throws.","triggerScenarios":"Called from rollbackLegacyCodexSync when recreating a legacy sync file: after openSync succeeds, fs.fstatSync reports the descriptor is not a regular file — e.g. a concurrent process replaced the path with a FIFO/socket/device between the create and the stat, or a non-POSIX filesystem (some network mounts) reports an unexpected type.","commonSituations":"Another tool re-creates the sync path as a FIFO or special file while rollback runs; exotic network filesystems (NFS with odd semantics, FUSE mounts) misreporting file types; adversarial race on a shared multi-user machine.","solutions":["Inspect the path (ls -la, stat) and remove any special file occupying it, then re-run rollback","Re-run the rollback command when no other process is writing to the path","Move the operation to a local filesystem instead of a network/FUSE mount","On a shared host, tighten permissions on the parent directory so other users cannot swap the path"],"exampleFix":"# before: check what occupies the path\nls -la <path>   # shows p (FIFO), s (socket), etc.\n# after: remove the special file and retry rollback\nrm <path>\nnpm run <rollback-command>","handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs';\ntry { fs.lstatSync(p); } catch (e) { if (e.code !== 'ENOENT') { /* path occupied by something odd */ } }\n// ensure parent dir is on a local filesystem and writable by the current user only","typeGuard":null,"tryCatchPattern":"try {\n  await rollbackLegacyCodexSync(p);\n} catch (err) {\n  if (err.message.includes('Refusing to create non-regular legacy sync path')) {\n    // inspect the path for special files, remove, and retry\n  } else throw err;\n}","preventionTips":["Run rollback on a local POSIX filesystem, not NFS/FUSE mounts","Ensure no other process writes to the path during rollback","Restrict parent directory permissions (0o755 or tighter) on multi-user hosts","Remove any FIFO/socket/device occupying the target path before running"],"tags":["filesystem","race-condition","symlink-safety","security"],"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"}