'HarnessAgent: `sandboxConfig.workDir` must use POSIX path s

Error message

'HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators.'

What it means

Sandbox work directories run inside a POSIX (Linux) sandbox, so `sandboxConfig.workDir` must use forward slashes. Backslashes are rejected because a Windows-style path like 'sub\dir' would be treated as a single filename with a literal backslash on POSIX, not nested directories.

Source

Thrown at packages/harness/src/agent/internal/sandbox-bootstrap.ts:47

    );
  }

  if (settings.workDir != null) {
    normalizeSandboxWorkDir(settings.workDir);
  }
}

export function normalizeSandboxWorkDir(workDir: string): string {
  if (workDir.length === 0) {
    throw new Error('HarnessAgent: `sandboxConfig.workDir` must not be empty.');
  }
  if (workDir.includes('\0')) {
    throw new Error(
      'HarnessAgent: `sandboxConfig.workDir` must not contain NUL.',
    );
  }
  if (workDir.includes('\\')) {
    throw new Error(
      'HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators.',
    );
  }
  if (posix.isAbsolute(workDir)) {
    throw new Error('HarnessAgent: `sandboxConfig.workDir` must be relative.');
  }

  const normalized = posix.normalize(workDir);
  if (
    normalized === '.' ||
    normalized === '..' ||
    normalized.startsWith('../')
  ) {
    throw new Error(
      'HarnessAgent: `sandboxConfig.workDir` must stay inside the sandbox default working directory.',
    );
  }
  return normalized;

View on GitHub (pinned to 69428b1f8b)

Solutions

Replace backslashes with forward slashes: use 'subdir/nested' instead of 'subdir\\nested'.
Build paths with node:path's posix module (path.posix.join) rather than the platform-default path module.
Convert programmatically before passing: workDir.replaceAll('\\', '/')

Example fix

// before
import { join } from 'node:path';
const workDir = join('workspace', 'runs'); // 'workspace\\runs' on Windows
// after
import { join } from 'node:path/posix';
const workDir = join('workspace', 'runs'); // 'workspace/runs'

Defensive patterns

Strategy: validation

Validate before calling

if (workDir.includes('\\')) throw new Error('workDir must use POSIX separators');

Type guard

function isPosixRelativePath(v: unknown): v is string { return typeof v === 'string' && !v.includes('\\'); }

Try / catch

try { await prepareSandboxForHarness({ sandboxConfig: { workDir }, harnesses }); } catch (e) { if (e.message.includes('POSIX path separators')) workDir = workDir.replaceAll('\\', '/'); else throw e; }

Prevention

Always build sandbox paths with node:path/posix
Never interpolate host OS paths directly into sandbox config
Normalize backslashes to slashes when ingesting user config

When it happens

Trigger: Setting sandboxConfig.workDir to a Windows-style relative path such as 'subdir\nested' when calling prepareSandboxForHarness or creating a harness agent with sandbox enabled.

Common situations: Developers on Windows building paths with path.win32.join or string concatenation using '\\'; hardcoded Windows paths copied into config files.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/b595167c06a1959b. Report an issue: GitHub.