stablyai/orca · error · Error

The target filesystem cannot safely install this rollout.

Error message

The target filesystem cannot safely install this rollout.

What it means

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.

Source

Thrown at src/main/codex/codex-legacy-session-resume.ts:151

  const sourceStat = await lstat(sourcePath)
  if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
    throw new Error('Legacy rollout source is not a regular file.')
  }
  await mkdir(dirname(targetPath), { recursive: true })
  try {
    await link(sourcePath, targetPath)
  } catch (linkError) {
    if (isExistsError(linkError)) {
      await assertMatchingExistingTarget(sourcePath, targetPath)
    } else {
      try {
        await copySessionFileWithoutOverwrite(sourcePath, targetPath)
      } catch (copyError) {
        if (isExistsError(copyError)) {
          await assertMatchingExistingTarget(sourcePath, targetPath)
        } else {
          if (isAtomicNoReplaceUnsupportedError(copyError)) {
            throw new Error('The target filesystem cannot safely install this rollout.', {
              cause: copyError
            })
          }
          throw copyError
        }
      }
    }
  }

  const summary = {
    stopped: false,
    scannedFiles: 1,
    linkedFiles: 0,
    copiedFiles: 0,
    skippedExistingFiles: 0,
    skippedUnexpectedFiles: 0,
    skippedSymlinkFiles: 0,
    skippedUnsupportedFilesystemFiles: 0,

View on GitHub (pinned to 1136503c6a)

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.

Defensive patterns

Strategy: fallback

Validate before calling

// Detect an atomic-write-incapable target volume before resume:
import { access, constants } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
// Attempt a probe O_EXCL write in the target dir; if it fails with the unsupported errno, decline the real-home lane.

Type guard

function isUnsafeFilesystemError(error: unknown): boolean {
  return error instanceof Error && error.message === 'The target filesystem cannot safely install this rollout.'
}

Try / catch

try {
  await prepareLegacySharedCodexSessionResume(args, options)
} catch (error) {
  if (isUnsafeFilesystemError(error)) {
    // move system Codex home to a POSIX-capable volume; or decline and use managed home
  } else throw error
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/edd29cdce9bc33c0. Report an issue: GitHub.