{"record":{"id":"ecb5d26e2bd94904","repo":"affaan-m/ECC","slug":"legacy-codex-sync-state-not-found-at-statepath","errorCode":null,"errorMessage":"Legacy Codex sync state not found at ${statePath}","messagePattern":"Legacy Codex sync state not found at (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/codex-legacy-sync.js","lineNumber":140,"sourceCode":"        `Legacy sync path changed before removal; preserved replacement at ${quarantinePath}`\n      );\n    }\n    throw new Error(`Legacy sync path changed before removal: ${filePath}`);\n  }\n  fs.unlinkSync(quarantinePath);\n  fs.rmdirSync(quarantineDir);\n}\n\nfunction atomicWriteJson(filePath, value) {\n  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });\n  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;\n  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\\n`, { mode: 0o600 });\n  fs.renameSync(tempPath, filePath);\n}\n\nfunction readState(statePath) {\n  const snapshot = readRegularFileNoFollow(statePath, 'utf8');\n  if (!snapshot) throw new Error(`Legacy Codex sync state not found at ${statePath}`);\n  return parseState(snapshot.content, statePath);\n}\n\nfunction readStateIfPresent(statePath) {\n  const snapshot = readRegularFileNoFollow(statePath, 'utf8');\n  return snapshot ? parseState(snapshot.content, statePath) : null;\n}\n\nfunction parseState(content, statePath) {\n  const state = JSON.parse(content);\n  if (state.schema !== SCHEMA || !Array.isArray(state.paths)) {\n    throw new Error(`Invalid legacy Codex sync state at ${statePath}`);\n  }\n  return state;\n}\n\nfunction hasUnsafeManagedAncestor(filePath, codexHome) {\n  const relativePath = path.relative(codexHome, filePath);","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/affaan-m/ECC/blob/06c5e118c4d3e6c3b7f9445f973a2194c82de193/scripts/lib/codex-legacy-sync.js#L122-L158","documentation":"readState is the strict reader for the legacy Codex sync state: readRegularFileNoFollow returned null, meaning the state file does not exist at statePath, and readState turns that into an explicit error. This is the precondition-failing variant — the sibling readStateIfPresent returns null instead for first-run scenarios, so hitting this error means a code path that requires prior sync state was invoked before any state was ever created.","triggerScenarios":"Running a sync subcommand that updates/prunes existing legacy state (via readState) on a machine where the initial sync never ran; the state file was deleted or moved; CODEX_HOME/ECC state dir points somewhere fresh.","commonSituations":"New machine or container with no prior Codex legacy sync; cleanup scripts deleting the state file; a changed state directory env var.","solutions":["Run the command that creates/initializes the legacy sync state first (the init/install sync path that uses readStateIfPresent semantics), then re-run.","Verify the expected path exists afterwards: ls -l <statePath>.","If the state dir was relocated, re-run setup so the state file is created at the new location."],"exampleFix":"# before\n$ ecc codex sync --prune-legacy   # no state file yet\n# Error: Legacy Codex sync state not found at ...\n\n# after\n$ ecc codex sync --init-legacy      # creates state first\n$ ecc codex sync --prune-legacy","handlingStrategy":"fallback","validationCode":"import fs from 'node:fs';\nfunction stateExists(p) { return fs.existsSync(p); }\nif (!stateExists(statePath)) { /* run the initializing sync command first */ }","typeGuard":"function hasLegacyState(p) {\n  try { return fs.lstatSync(p).isFile(); } catch { return false; }\n}","tryCatchPattern":"try { state = readState(statePath); } catch (e) {\n  if (/Legacy Codex sync state not found/.test(e.message)) { state = defaultState; /* first-run fallback */ }\n  else throw e;\n}","preventionTips":["Use the readStateIfPresent code path (or an existence check) when first-run is a legitimate state.","Run the state-creating sync command once as part of machine setup before any prune/update flows."],"tags":["filesystem","state-management","codex-sync","first-run"],"backgroundTag":"missing-state-file","analyzedSha":"06c5e118c4d3e6c3b7f9445f973a2194c82de193","analyzedAt":"2026-08-18T11:27:13.915Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}