{"record":{"id":"edd29cdce9bc33c0","repo":"stablyai/orca","slug":"the-target-filesystem-cannot-safely-install-this-r","errorCode":null,"errorMessage":"The target filesystem cannot safely install this rollout.","messagePattern":"The target filesystem cannot safely install this rollout\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/codex/codex-legacy-session-resume.ts","lineNumber":151,"sourceCode":"  const sourceStat = await lstat(sourcePath)\n  if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {\n    throw new Error('Legacy rollout source is not a regular file.')\n  }\n  await mkdir(dirname(targetPath), { recursive: true })\n  try {\n    await link(sourcePath, targetPath)\n  } catch (linkError) {\n    if (isExistsError(linkError)) {\n      await assertMatchingExistingTarget(sourcePath, targetPath)\n    } else {\n      try {\n        await copySessionFileWithoutOverwrite(sourcePath, targetPath)\n      } catch (copyError) {\n        if (isExistsError(copyError)) {\n          await assertMatchingExistingTarget(sourcePath, targetPath)\n        } else {\n          if (isAtomicNoReplaceUnsupportedError(copyError)) {\n            throw new Error('The target filesystem cannot safely install this rollout.', {\n              cause: copyError\n            })\n          }\n          throw copyError\n        }\n      }\n    }\n  }\n\n  const summary = {\n    stopped: false,\n    scannedFiles: 1,\n    linkedFiles: 0,\n    copiedFiles: 0,\n    skippedExistingFiles: 0,\n    skippedUnexpectedFiles: 0,\n    skippedSymlinkFiles: 0,\n    skippedUnsupportedFilesystemFiles: 0,","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/codex/codex-legacy-session-resume.ts#L133-L169","documentation":"Thrown when both hard-linking (link()) and the fallback atomic copy (copySessionFileWithoutOverwrite) failed, and the copy error is classified by isAtomicNoReplaceUnsupportedError — meaning the target filesystem cannot perform an atomic no-replace write. Orca refuses to install a rollout without an atomic guarantee because a partial write would corrupt the session index.","triggerScenarios":"The target lives on a filesystem (some network shares, FAT/exFAT, or virtualized mounts) that doesn't support O_EXCL/atomic temp-rename; link() failed with EXDEV (cross-device) and the copy fallback's atomic primitive returned an unsupported errno.","commonSituations":"CODEX_HOME on a network drive (SMB/NFS) without atomic rename; an external/exFAT drive; a containerized mount lacking O_TMPFILE/O_EXCL; a fuse filesystem with limited semantics.","solutions":["Move the system Codex home (paths.systemSessionsRoot) to a filesystem supporting atomic writes (ext4, APFS, NTFS).","If a network share is required, use a local home and sync separately.","For cross-device link failures (EXDEV), ensure source and target are on the same volume.","Decline the real-home lane and keep resume on the managed home where atomic guarantees hold."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Detect an atomic-write-incapable target volume before resume:\nimport { access, constants } from 'node:fs/promises'\nimport { tmpdir } from 'node:os'\nimport { join } from 'node:path'\n// Attempt a probe O_EXCL write in the target dir; if it fails with the unsupported errno, decline the real-home lane.","typeGuard":"function isUnsafeFilesystemError(error: unknown): boolean {\n  return error instanceof Error && error.message === 'The target filesystem cannot safely install this rollout.'\n}","tryCatchPattern":"try {\n  await prepareLegacySharedCodexSessionResume(args, options)\n} catch (error) {\n  if (isUnsafeFilesystemError(error)) {\n    // move system Codex home to a POSIX-capable volume; or decline and use managed home\n  } else throw error\n}","preventionTips":["Keep CODEX_HOME on a filesystem supporting atomic rename (ext4/APFS/NTFS).","Avoid FAT/exFAT and some network shares for the sessions root.","Ensure source and target are on the same device to allow hardlinks.","If stuck on a limited FS, decline the real-home lane and use managed resume."],"tags":["codex","session-resume","legacy","filesystem","atomic-write","network-fs"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}