paperclipai/paperclip · error · Error

Timed out checking working directory on remote target: "${cw

Error message

Timed out checking working directory on remote target: "${cwd}"

What it means

Thrown by ensureAdapterExecutionTargetDirectory when the shell command that checks or creates the working directory on a remote target times out. The command is either `mkdir -p <cwd> && [ -d <cwd> ]` (createIfMissing) or `[ -d <cwd> ]`, run with a 15s default timeout and 5s grace period.

Source

Thrown at packages/adapter-utils/src/execution-target.ts:1007

  if (!cwd.startsWith("/")) {
    throw new Error(`Working directory must be an absolute POSIX path on the remote target: "${cwd}"`);
  }

  const quoted = shellQuote(cwd);
  const script = createIfMissing
    ? `mkdir -p ${quoted} && [ -d ${quoted} ]`
    : `[ -d ${quoted} ]`;

  const result = await runAdapterExecutionTargetShellCommand(runId, target, script, {
    cwd: target.kind === "remote" ? target.remoteCwd : cwd,
    env: options.env,
    timeoutSec: options.timeoutSec ?? 15,
    graceSec: options.graceSec ?? 5,
    onLog: options.onLog,
  });

  if (result.timedOut) {
    throw new Error(`Timed out checking working directory on remote target: "${cwd}"`);
  }
  if ((result.exitCode ?? 1) !== 0) {
    const detail = (result.stderr || result.stdout || "").trim();
    if (createIfMissing) {
      throw new Error(
        `Could not create working directory "${cwd}" on remote target${detail ? `: ${detail}` : "."}`,
      );
    }
    throw new Error(
      `Working directory does not exist on remote target: "${cwd}"${detail ? ` (${detail})` : ""}`,
    );
  }
}

export function adapterExecutionTargetSessionIdentity(
  target: AdapterExecutionTarget | null | undefined,
): Record<string, unknown> | null {
  if (!target || target.kind === "local") return null;

View on GitHub (pinned to 67001ec6eb)

Solutions

Increase the options.timeoutSec above the default 15s if the remote filesystem is slow.
Verify the SSH/sandbox connection is healthy and not blocked on interactive prompts.
Check if the remote filesystem is an NFS or fuse mount that could hang on directory operations.
Ensure the sandbox lease is still active.

Defensive patterns

Strategy: retry

Try / catch

try {
  await ensureAdapterExecutionTargetDirectory(runId, target, cwd, options);
} catch (err) {
  if (err instanceof Error && err.message.includes("Timed out checking working directory")) {
    // Remote may be transiently slow — retry with a longer timeout
    await ensureAdapterExecutionTargetDirectory(runId, target, cwd, { ...options, timeoutSec: 60 });
  } else {
    throw err;
  }
}

Prevention

Set options.timeoutSec above 15s for slow remote filesystems.
Verify SSH connections are non-interactive (no password/host-key prompts).
Monitor remote host latency and resource availability.

When it happens

Trigger: Calling ensureAdapterExecutionTargetDirectory(runId, target, cwd, options) with a remote target; runAdapterExecutionTargetShellCommand returns { timedOut: true } for the directory check script.

Common situations: The remote SSH connection or sandbox exec channel is stalled; the filesystem is on a slow network mount (NFS) causing the stat to hang; the sandbox lease expired; the SSH session is waiting on a password prompt or host-key verification.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/8315de199bd57436. Report an issue: GitHub.