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.

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.

Appendix: 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)