abhigyanpatwari/GitNexus · error · AggregateError

Clone failed and partial checkout could not be quarantined

Error message

Clone failed and partial checkout could not be quarantined: ${safeTarget}

What it means

After a clone failure, cloneOrPull tries to quarantine a partial checkout via quarantineAutoSyncPartial; if quarantine itself fails, the original clone error and the quarantine error are rethrown together as an AggregateError. This tells you the clone failed AND a broken partial checkout remains in place at safeTarget.

Solutions

Fix the quarantine destination (check options.quarantineRoot exists and is writable) and retry.
Manually remove the partial checkout at safeTarget, then re-run the clone.
Read the AggregateError.errors array: address the underlying clone failure first, then the quarantine failure.
Check filesystem permissions and free space on both the clone root and quarantine root.

Example fix

// before
await cloneOrPull({ url, targetDir });
// after: inspect both wrapped errors, then clean up and retry
try {
  await cloneOrPull({ url, targetDir, quarantineRoot: '/var/tmp/gnx-quarantine' });
} catch (e) {
  if (e instanceof AggregateError) console.error(e.errors);
}

Defensive patterns

Strategy: try-catch

Validate before calling

await fs.mkdir(quarantineRoot, { recursive: true });
await fs.access(quarantineRoot, (await import('node:fs')).constants.W_OK); // ensure quarantine is writable before cloning

Try / catch

try {
  await cloneOrPull(opts);
} catch (err) {
  if (err instanceof AggregateError && err.message.includes('could not be quarantined')) {
    for (const inner of err.errors) console.error('clone/quarantine failure:', inner);
    // clean up partial checkout manually, fix quarantineRoot, then retry
  } else {
    throw err;
  }
}

Prevention

Provision quarantineRoot with the same ownership/permissions as the clone root.
Monitor disk space on both clone and quarantine volumes.
Retry clones on transient network errors so partial states are less likely.
Unwrap and log AggregateError.errors individually — there are always two distinct causes.

When it happens

Trigger: The git clone subprocess fails (network, auth, bad branch) while a partial target directory exists, and quarantineAutoSyncPartial throws (e.g. quarantineRoot unwritable, permission denied moving the directory).

Common situations: Flaky network plus a read-only or full quarantine disk; permission mismatch on the clone root preventing the rename/move; concurrent processes holding the partial directory open; SELinux/container mount restrictions on moving directories.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-08). Data as JSON: /api/errors/c65175854e07c3bd. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/server/git-clone.ts:673

        ? buildBranchCloneArgs(url, safeTarget, options.branch)
        : buildCloneArgs(url, safeTarget);
      await runGitImpl(cloneArgs, undefined, {
        token: options?.token,
        url,
        timeoutMs: options?.timeoutMs,
      });
      await assertPostRealpathContainment(cloneRoot, safeTarget);
    } catch (err: unknown) {
      if (options?.quarantineRoot) {
        const partialExists = await fs.access(safeTarget).then(
          () => true,
          () => false,
        );
        if (partialExists) {
          try {
            await quarantineAutoSyncPartial(safeTarget, options.quarantineRoot);
          } catch (quarantineError) {
            throw new AggregateError(
              [err, quarantineError],
              `Clone failed and partial checkout could not be quarantined: ${safeTarget}`,
            );
          }
        }
      }
      throw err;
    }
  }

  return safeTarget;
}

async function assertPreRealpathContainment(root: string, target: string): Promise<void> {
  const realRoot = await fs.realpath(root);
  const realParent = await fs.realpath(path.dirname(target));
  const parentRel = path.relative(realRoot, realParent);
  if (parentRel.startsWith('..') || path.isAbsolute(parentRel)) {

View on GitHub (pinned to ac9a4e9abd)