{"record":{"id":"b595167c06a1959b","repo":"vercel/ai","slug":"harnessagent-sandboxconfig-workdir-must-use-po","errorCode":null,"errorMessage":"'HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators.'","messagePattern":"'HarnessAgent: `sandboxConfig\\.workDir` must use POSIX path separators\\.'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness/src/agent/internal/sandbox-bootstrap.ts","lineNumber":47,"sourceCode":"    );\n  }\n\n  if (settings.workDir != null) {\n    normalizeSandboxWorkDir(settings.workDir);\n  }\n}\n\nexport function normalizeSandboxWorkDir(workDir: string): string {\n  if (workDir.length === 0) {\n    throw new Error('HarnessAgent: `sandboxConfig.workDir` must not be empty.');\n  }\n  if (workDir.includes('\\0')) {\n    throw new Error(\n      'HarnessAgent: `sandboxConfig.workDir` must not contain NUL.',\n    );\n  }\n  if (workDir.includes('\\\\')) {\n    throw new Error(\n      'HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators.',\n    );\n  }\n  if (posix.isAbsolute(workDir)) {\n    throw new Error('HarnessAgent: `sandboxConfig.workDir` must be relative.');\n  }\n\n  const normalized = posix.normalize(workDir);\n  if (\n    normalized === '.' ||\n    normalized === '..' ||\n    normalized.startsWith('../')\n  ) {\n    throw new Error(\n      'HarnessAgent: `sandboxConfig.workDir` must stay inside the sandbox default working directory.',\n    );\n  }\n  return normalized;","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness/src/agent/internal/sandbox-bootstrap.ts#L29-L65","documentation":"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.","triggerScenarios":"Setting sandboxConfig.workDir to a Windows-style relative path such as 'subdir\\nested' when calling prepareSandboxForHarness or creating a harness agent with sandbox enabled.","commonSituations":"Developers on Windows building paths with path.win32.join or string concatenation using '\\\\'; hardcoded Windows paths copied into config files.","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('\\\\', '/')"],"exampleFix":"// before\nimport { join } from 'node:path';\nconst workDir = join('workspace', 'runs'); // 'workspace\\\\runs' on Windows\n// after\nimport { join } from 'node:path/posix';\nconst workDir = join('workspace', 'runs'); // 'workspace/runs'","handlingStrategy":"validation","validationCode":"if (workDir.includes('\\\\')) throw new Error('workDir must use POSIX separators');","typeGuard":"function isPosixRelativePath(v: unknown): v is string { return typeof v === 'string' && !v.includes('\\\\'); }","tryCatchPattern":"try { await prepareSandboxForHarness({ sandboxConfig: { workDir }, harnesses }); } catch (e) { if (e.message.includes('POSIX path separators')) workDir = workDir.replaceAll('\\\\', '/'); else throw e; }","preventionTips":["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"],"tags":["path","windows","posix","validation"],"backgroundTag":"windows-path-separator","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}