{"record":{"id":"0882330a88b282c4","repo":"paperclipai/paperclip","slug":"working-directory-must-be-an-absolute-posix-path-o","errorCode":null,"errorMessage":"Working directory must be an absolute POSIX path on the remote target: \"${cwd}\"","messagePattern":"Working directory must be an absolute POSIX path on the remote target: \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapter-utils/src/execution-target.ts","lineNumber":990,"sourceCode":" * Throws an Error with a human-readable message on failure.\n */\nexport async function ensureAdapterExecutionTargetDirectory(\n  runId: string,\n  target: AdapterExecutionTarget | null | undefined,\n  cwd: string,\n  options: AdapterExecutionTargetShellOptions & { createIfMissing?: boolean },\n): Promise<void> {\n  const createIfMissing = options.createIfMissing ?? false;\n\n  if (!target || target.kind === \"local\") {\n    const { ensureAbsoluteDirectory } = await import(\"./server-utils.js\");\n    await ensureAbsoluteDirectory(cwd, { createIfMissing });\n    return;\n  }\n\n  // Remote (SSH or sandbox): both expect POSIX absolute paths inside the env.\n  if (!cwd.startsWith(\"/\")) {\n    throw new Error(`Working directory must be an absolute POSIX path on the remote target: \"${cwd}\"`);\n  }\n\n  const quoted = shellQuote(cwd);\n  const script = createIfMissing\n    ? `mkdir -p ${quoted} && [ -d ${quoted} ]`\n    : `[ -d ${quoted} ]`;\n\n  const result = await runAdapterExecutionTargetShellCommand(runId, target, script, {\n    cwd: target.kind === \"remote\" ? target.remoteCwd : cwd,\n    env: options.env,\n    timeoutSec: options.timeoutSec ?? 15,\n    graceSec: options.graceSec ?? 5,\n    onLog: options.onLog,\n  });\n\n  if (result.timedOut) {\n    throw new Error(`Timed out checking working directory on remote target: \"${cwd}\"`);\n  }","sourceCodeStart":972,"sourceCodeEnd":1008,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/execution-target.ts#L972-L1008","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the cwd passed to ensureAdapterExecutionTargetDirectory is an absolute POSIX path (starts with '/').","Validate and normalize paths at the adapter configuration layer before they reach the execution target.","If the path originates from user input or agent config, resolve it against the target's remoteCwd or home directory before calling."],"exampleFix":"// before\nawait ensureAdapterExecutionTargetDirectory(runId, target, \"workspace/repo\", { createIfMissing: true });\n// after\nawait ensureAdapterExecutionTargetDirectory(runId, target, \"/home/user/workspace/repo\", { createIfMissing: true });","handlingStrategy":"validation","validationCode":"function validateRemoteCwd(cwd: string): void {\n  if (!cwd.startsWith(\"/\")) {\n    throw new Error(`cwd must be an absolute POSIX path for remote targets, got: \"${cwd}\"`);\n  }\n}\n// Call before ensureAdapterExecutionTargetDirectory\nvalidateRemoteCwd(cwd);","typeGuard":"function isAbsolutePosixPath(value: string): boolean {\n  return typeof value === \"string\" && value.startsWith(\"/\");\n}","tryCatchPattern":null,"preventionTips":["Always resolve cwd to an absolute POSIX path before passing to remote-target functions.","Validate paths at the adapter configuration boundary, not at the execution layer.","Use path.posix.resolve() when constructing paths for remote targets."],"tags":["path-validation","execution-target","remote","adapter-utils"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}