paperclipai/paperclip · error · Error

Working directory must be an absolute POSIX path on the remo

Error message

Working directory must be an absolute POSIX path on the remote target: "${cwd}"

What it means

Thrown by ensureAdapterExecutionTargetDirectory when the working directory path for a remote (SSH or sandbox) target does not begin with '/'. Remote targets run POSIX shells, so a relative path like 'workspace/foo' or a Windows-style path cannot be used. Local targets are not affected because they delegate to Node's ensureAbsoluteDirectory.

Source

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

 * Throws an Error with a human-readable message on failure.
 */
export async function ensureAdapterExecutionTargetDirectory(
  runId: string,
  target: AdapterExecutionTarget | null | undefined,
  cwd: string,
  options: AdapterExecutionTargetShellOptions & { createIfMissing?: boolean },
): Promise<void> {
  const createIfMissing = options.createIfMissing ?? false;

  if (!target || target.kind === "local") {
    const { ensureAbsoluteDirectory } = await import("./server-utils.js");
    await ensureAbsoluteDirectory(cwd, { createIfMissing });
    return;
  }

  // Remote (SSH or sandbox): both expect POSIX absolute paths inside the env.
  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}"`);
  }

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Ensure the cwd passed to ensureAdapterExecutionTargetDirectory is an absolute POSIX path (starts with '/').
2. Validate and normalize paths at the adapter configuration layer before they reach the execution target.
3. If the path originates from user input or agent config, resolve it against the target's remoteCwd or home directory before calling.

Example fix

// before
await ensureAdapterExecutionTargetDirectory(runId, target, "workspace/repo", { createIfMissing: true });
// after
await ensureAdapterExecutionTargetDirectory(runId, target, "/home/user/workspace/repo", { createIfMissing: true });

function validateRemoteCwd(cwd: string): void {
  if (!cwd.startsWith("/")) {
    throw new Error(`cwd must be an absolute POSIX path for remote targets, got: "${cwd}"`);
  }
}
// Call before ensureAdapterExecutionTargetDirectory
validateRemoteCwd(cwd);

function isAbsolutePosixPath(value: string): boolean {
  return typeof value === "string" && value.startsWith("/");
}

When it happens

Trigger: Calling ensureAdapterExecutionTargetDirectory(runId, target, cwd, options) where target.kind === 'remote' and cwd does not start with '/'. This happens before any shell command is sent to the remote.

Common situations: A relative path leaks through from agent configuration or workspace setup into the remote cwd; a Windows-style path (C:\\...) is passed to a Linux sandbox; the cwd field is accidentally set to an empty string or a bare directory name.

Related errors

• Timed out checking working directory on remote target: "${cw
• Could not create working directory "${cwd}" on remote target
• Working directory does not exist on remote target: "${cwd}"$
• Timed out checking command "${command}" on sandbox target.
• Command "${command}" is not installed or not on PATH in the

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