paperclipai/paperclip · error

${label} must be an absolute path.

Error message

${label} must be an absolute path.

What it means

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').

Source

Thrown at packages/adapter-utils/src/local-process-sandbox.ts:77

  "/etc/resolv.conf",
  "/etc/hosts",
  "/etc/nsswitch.conf",
  "/etc/passwd",
  "/etc/group",
  "/etc/localtime",
  "/etc/timezone",
  "/etc/gitconfig",
] as const;

const PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"] as const;
const SANDBOX_PROXY_PORT = 31_337;
const UNIX_SOCKET_PATH_MAX_BYTES = 107;
const NETWORK_PROXY_TEMP_PREFIX = "paperclip-network-sandbox-";

function normalizeAbsolutePath(candidate: string, label: string): string {
  const trimmed = candidate.trim();
  if (!trimmed || !path.isAbsolute(trimmed)) {
    throw new Error(`${label} must be an absolute path.`);
  }
  return path.resolve(trimmed);
}

async function pathExists(candidate: string): Promise<boolean> {
  return fs.lstat(candidate).then(() => true).catch(() => false);
}

function parentDirectories(candidate: string): string[] {
  const directories: string[] = [];
  let current = path.dirname(candidate);
  while (current !== path.dirname(current)) {
    directories.push(current);
    current = path.dirname(current);
  }
  return directories.reverse();
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Ensure all path arguments passed to the local process sandbox are absolute (start with '/' on POSIX or a drive letter on Windows).
2. Use path.resolve() or path.join(process.cwd(), relativePath) to convert relative paths before passing them.
3. Check the label in the error message to identify exactly which field needs fixing.

Example fix

// before
const sandbox = await createLocalProcessSandbox({
  cwd: "workspace/repo",
  options: { workspaceDir: "sandbox/ws" },
});
// after
const sandbox = await createLocalProcessSandbox({
  cwd: path.resolve("workspace/repo"),
  options: { workspaceDir: path.resolve("sandbox/ws") },
});

function validateSandboxPaths(input: LocalProcessSandboxInput): void {
  const checks: Array<[string, string]> = [
    ["workspaceDir", input.options.workspaceDir],
    ["cwd", input.cwd],
  ];
  for (const [label, candidate] of checks) {
    if (!path.isAbsolute(candidate)) {
      throw new Error(`${label} must be an absolute path, got: "${candidate}"`);
    }
  }
}

function isAbsolutePath(value: unknown): value is string {
  return typeof value === "string" && path.isAbsolute(value);
}

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• networkAllowlist[${index}] must not be empty.
• networkAllowlist[${index}] must be a hostname, hostname:port
• networkAllowlist[${index}] must use an exact hostname; wildc
• ${action} failed with exit code ${result.exitCode ?? "null"}
• post-upload command cwd is not a confined absolute POSIX pat

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