paperclipai/paperclip · error · Error

Working directory must be an absolute path: "${cwd}"

Error message

Working directory must be an absolute path: "${cwd}"

What it means

Thrown by ensureAbsoluteDirectory when the given cwd is not an absolute path (path.isAbsolute returns false). This is the first guard in directory preparation — the orchestrator requires an absolute working directory so that subsequent fs operations and sandbox confinement are unambiguous across platforms. It runs before any existence check.

Source

Thrown at packages/adapter-utils/src/server-utils.ts:2424

      args: ["/d", "/s", "/c", commandLine],
    };
  }

  return { command: executable, args };
}

export function ensurePathInEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
  if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
  if (typeof env.Path === "string" && env.Path.length > 0) return env;
  return { ...env, PATH: defaultPathForPlatform() };
}

export async function ensureAbsoluteDirectory(
  cwd: string,
  opts: { createIfMissing?: boolean } = {},
) {
  if (!path.isAbsolute(cwd)) {
    throw new Error(`Working directory must be an absolute path: "${cwd}"`);
  }

  const assertDirectory = async () => {
    const stats = await fs.stat(cwd);
    if (!stats.isDirectory()) {
      throw new Error(`Working directory is not a directory: "${cwd}"`);
    }
  };

  try {
    await assertDirectory();
    return;
  } catch (err) {
    const code = (err as NodeJS.ErrnoException).code;
    if (!opts.createIfMissing || code !== "ENOENT") {
      if (code === "ENOENT") {
        throw new Error(`Working directory does not exist: "${cwd}"`);
      }

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Resolve cwd with path.resolve() (or path.posix.resolve for remote POSIX targets) before calling ensureAbsoluteDirectory.
2. Expand '~' via expandHomePrefix and strip leading './' when collecting the cwd value.
3. Validate cwd with path.isAbsolute at the config-loading boundary.
4. For remote POSIX execution use POSIX-style absolute paths regardless of the orchestrator's OS.

Example fix

// before
await ensureAbsoluteDirectory('./workspace');
// after
await ensureAbsoluteDirectory(path.resolve('./workspace'));

if (!path.isAbsolute(cwd)) {
  throw new Error(`cwd must be absolute: ${cwd}`);
}
// or just resolve upstream:
cwd = path.resolve(cwd);

function isAbsolutePath(p: string): boolean { return typeof p === 'string' && path.isAbsolute(p); }

When it happens

Trigger: Calling ensureAbsoluteDirectory(cwd) or a higher-level spawn path that derives cwd from a relative value (e.g. './repo', 'workspace', 'a/b'). path.isAbsolute is platform-aware, so a POSIX-style '/x' on Windows or a Windows 'C:\x' on Linux can also trip it.

Common situations: Caller passed process-relative cwd from a config field that was meant to be resolved; cross-platform path string shipped to the wrong OS; a leading './' or '~' not expanded; cwd read from argv without normalization.

Related errors

• Working directory is not a directory: "${cwd}"
• Working directory does not exist: "${cwd}"
• Export output path ${root} exists and is not a directory.
• Export output directory ${root} already contains files. Re-r
• Worktree config already exists at ${paths.configPath} or ins

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