What causes "Codex working directory cannot be a filesystem root" in paperclipai/paperclip?

Point the working directory at a specific workspace subdirectory instead of the root

Codex working directory cannot be a filesystem root

Error message

Codex working directory cannot be a filesystem root

What it means

The validator refuses a working directory that resolves to a filesystem root (e.g. `/` on POSIX). Allowing a provider session to run at the root would expose the entire filesystem to the agent and break the workspace containment model, so root is categorically rejected.

Source

Thrown at packages/paperclip-runner/src/drivers/codex/codex-boundaries.ts:69

  }
  const requested = resolve(workingDirectory);
  let resolved: string;
  try {
    resolved = realpathSync.native(requested);
    if (!statSync(resolved).isDirectory()) {
      throw new Error("Codex working directory must be a directory");
    }
  } catch (error) {
    const code = (error as NodeJS.ErrnoException).code;
    if (code === "ENOENT") {
      throw new Error(
        "Codex working directory must exist before provider admission",
      );
    }
    throw error;
  }
  if (resolved === parse(resolved).root) {
    throw new Error("Codex working directory cannot be a filesystem root");
  }
  const configuredRoot = environment.PAPERCLIP_WORKSPACE_CWD;
  const hostHome = canonicalConfiguredPath(environment.HOME);
  if (hostHome && pathContains(resolved, hostHome)) {
    throw new Error("Codex working directory cannot contain the host HOME");
  }
  if (
    hostHome &&
    SENSITIVE_HOST_HOME_DIRECTORIES.some((directory) =>
      pathContains(resolve(hostHome, directory), resolved),
    )
  ) {
    throw new Error(
      "Codex working directory cannot overlap sensitive host HOME state",
    );
  }
  if (
    hostHome &&

View on GitHub (pinned to 01ad858492)

Solutions

Point the working directory at a specific workspace subdirectory instead of the root
Fix the config transformation that strips the workspace path prefix
Add a pre-check that rejects root paths before calling the driver

Example fix

// before
const cwd = workspacePath.replace("/workspaces", ""); // leaves "/" when path IS /workspaces
// after
const cwd = workspacePath.startsWith("/workspaces/") ? workspacePath : `/workspaces/${task.id}`;

Defensive patterns

Strategy: validation

Validate before calling

import { resolve, parse } from "node:path";
if (resolve(cwd) === parse(resolve(cwd)).root) {
  throw new Error("working directory must not be a filesystem root");
}

Type guard

function isFilesystemRoot(p: string): boolean {
  const r = resolve(p);
  return r === parse(r).root;
}

Try / catch

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message.includes("cannot be a filesystem root")) {
    throw new ConfigError("workspace path collapsed to root; check path construction");
  }
  throw err;
}

Prevention

Never use bare "/" or drive roots as workspace defaults
Join workspace root + task id so the path always has depth
Log the resolved path before validation when debugging path construction

When it happens

Trigger: Passing `/` (or `C:\` on Windows) as the working directory, or a path that resolves to the root after normalization (e.g. `/..`).

Common situations: Default fallback values that use the root path; misparsed configuration where a path prefix was stripped leaving only `/`; a sandbox config that dropped the workspace subpath.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/832d3668837b9af1. Report an issue: GitHub.