paperclipai/paperclip · error

Codex working directory is required

Error message

Codex working directory is required

What it means

`validateCodexWorkingDirectory` is the boundary gate every Codex run passes through before the provider is admitted. It rejects a working directory that is empty or whitespace-only, because the driver cannot spawn or sandbox a session without a concrete filesystem location. This is the first check in the validation chain.

Source

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

  ".ssh",
] as const;

export type CodexWorkingDirectoryAuthority =
  "local_filesystem" | "remote_runner";

function record(value: unknown): Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

export function validateCodexWorkingDirectory(
  workingDirectory: string,
  environment: NodeJS.ProcessEnv = process.env,
  authority: CodexWorkingDirectoryAuthority = "local_filesystem",
): string {
  if (workingDirectory.trim().length === 0) {
    throw new Error("Codex working directory is required");
  }
  if (authority === "remote_runner") {
    return validateRemoteRunnerWorkingDirectory(workingDirectory, environment);
  }
  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",
      );
    }

View on GitHub (pinned to 01ad858492)

Solutions

1. Ensure the task/company record has a non-empty working directory before invoking the driver
2. Fix upstream config so the workspace path is populated (e.g. PAPERCLIP_WORKSPACE_CWD assignment logic)
3. Trim and validate user/config input before calling the driver

Example fix

// before
const cwd = task.workspaceCwd ?? "";
validateCodexWorkingDirectory(cwd);
// after
if (!task.workspaceCwd) throw new Error("task has no assigned workspace");
validateCodexWorkingDirectory(task.workspaceCwd);

if (typeof cwd !== "string" || cwd.trim().length === 0) {
  throw new Error("working directory must be a non-empty string");
}

function isNonEmptyString(v: unknown): v is string {
  return typeof v === "string" && v.trim().length > 0;
}

try {
  validateCodexWorkingDirectory(cwd);
} catch (err) {
  if (err.message === "Codex working directory is required") {
    throw new ConfigError(`task ${task.id} has no assigned workspace path`);
  }
  throw err;
}

When it happens

Trigger: Calling `validateCodexWorkingDirectory("")`, a string of spaces, or passing an undefined-but-coerced value from configuration where the workspace cwd was never assigned.

Common situations: Misconfigured task/run record with a null workspace path; environment provisioning failed to create the workspace field; a template that forgot to interpolate the working directory variable.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Paperclip Runner currently supports Codex only with codexPer
• ${label} must be an integer between 1 and ${maximum}.
• PAPERCLIP_EVAL_MAX_CAMPAIGN_COST_USD must be a positive fini
• Runner live rotation requires a valid generated-at time
• --agent-name cannot be empty.

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