{"record":{"id":"9db67b2b2dd8a5ae","repo":"paperclipai/paperclip","slug":"label-must-be-an-absolute-path","errorCode":null,"errorMessage":"${label} must be an absolute path.","messagePattern":"(.+?) must be an absolute path\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/adapter-utils/src/local-process-sandbox.ts","lineNumber":77,"sourceCode":"  \"/etc/resolv.conf\",\n  \"/etc/hosts\",\n  \"/etc/nsswitch.conf\",\n  \"/etc/passwd\",\n  \"/etc/group\",\n  \"/etc/localtime\",\n  \"/etc/timezone\",\n  \"/etc/gitconfig\",\n] as const;\n\nconst PROXY_ENV_KEYS = [\"HTTP_PROXY\", \"HTTPS_PROXY\", \"ALL_PROXY\", \"http_proxy\", \"https_proxy\", \"all_proxy\"] as const;\nconst SANDBOX_PROXY_PORT = 31_337;\nconst UNIX_SOCKET_PATH_MAX_BYTES = 107;\nconst NETWORK_PROXY_TEMP_PREFIX = \"paperclip-network-sandbox-\";\n\nfunction normalizeAbsolutePath(candidate: string, label: string): string {\n  const trimmed = candidate.trim();\n  if (!trimmed || !path.isAbsolute(trimmed)) {\n    throw new Error(`${label} must be an absolute path.`);\n  }\n  return path.resolve(trimmed);\n}\n\nasync function pathExists(candidate: string): Promise<boolean> {\n  return fs.lstat(candidate).then(() => true).catch(() => false);\n}\n\nfunction parentDirectories(candidate: string): string[] {\n  const directories: string[] = [];\n  let current = path.dirname(candidate);\n  while (current !== path.dirname(current)) {\n    directories.push(current);\n    current = path.dirname(current);\n  }\n  return directories.reverse();\n}\n","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/packages/adapter-utils/src/local-process-sandbox.ts#L59-L95","documentation":"Thrown by normalizeAbsolutePath in the local process sandbox when a path argument (workspaceDir, cwd, extraPaths, pathAliases, outboundRestorePaths, filesystemExtraPaths) is not an absolute path. The label in the message identifies which configuration field is invalid (e.g. 'Sandbox workspaceDir', 'Sandbox cwd', 'Sandbox extraPaths[0].path').","triggerScenarios":"Calling createLocalProcessSandbox or related functions with input.options.workspaceDir, input.cwd, or entries in extraPaths/outboundRestorePaths/pathAliases/filesystemExtraPaths that do not pass path.isAbsolute(). For example, passing 'workspace/repo' instead of '/home/user/workspace/repo'.","commonSituations":"Agent configuration or workspace setup provides a relative path where an absolute one is required; a path is constructed by joining a base directory incorrectly; Windows paths (C:\\\\...) passed on a POSIX system; a default path constant is accidentally set to a relative value.","solutions":["Ensure all path arguments passed to the local process sandbox are absolute (start with '/' on POSIX or a drive letter on Windows).","Use path.resolve() or path.join(process.cwd(), relativePath) to convert relative paths before passing them.","Check the label in the error message to identify exactly which field needs fixing."],"exampleFix":"// before\nconst sandbox = await createLocalProcessSandbox({\n  cwd: \"workspace/repo\",\n  options: { workspaceDir: \"sandbox/ws\" },\n});\n// after\nconst sandbox = await createLocalProcessSandbox({\n  cwd: path.resolve(\"workspace/repo\"),\n  options: { workspaceDir: path.resolve(\"sandbox/ws\") },\n});","handlingStrategy":"validation","validationCode":"function validateSandboxPaths(input: LocalProcessSandboxInput): void {\n  const checks: Array<[string, string]> = [\n    [\"workspaceDir\", input.options.workspaceDir],\n    [\"cwd\", input.cwd],\n  ];\n  for (const [label, candidate] of checks) {\n    if (!path.isAbsolute(candidate)) {\n      throw new Error(`${label} must be an absolute path, got: \"${candidate}\"`);\n    }\n  }\n}","typeGuard":"function isAbsolutePath(value: unknown): value is string {\n  return typeof value === \"string\" && path.isAbsolute(value);\n}","tryCatchPattern":null,"preventionTips":["Use path.resolve() to convert relative paths to absolute before passing to sandbox functions.","Validate all path inputs at the configuration boundary.","Use TypeScript's template literal types or branded types to distinguish absolute paths from relative ones."],"tags":["path-validation","sandbox","local-process-sandbox","adapter-utils"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}