'HarnessAgent: `sandboxConfig.workDir` must be relative.'

Error message

'HarnessAgent: `sandboxConfig.workDir` must be relative.'

What it means

The sandbox work directory must be a path relative to the sandbox's default working directory. Absolute paths (posix.isAbsolute) are rejected because the library resolves workDir against the sandbox's internal root, and absolute input could point outside the sandbox root it controls.

Source

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

  }
}

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;
}

export function resolveSessionWorkDir({
  defaultWorkingDirectory,
  harnessId,

View on GitHub (pinned to 69428b1f8b)

Solutions

Remove the leading slash and pass a relative path, e.g. 'workspace/runs' instead of '/workspace/runs'.
If you have an absolute host path, extract the relevant relative portion (path.posix.relative(root, absPath)).
Check config files for values that accidentally start with '/'.

Example fix

// before
await prepareSandboxForHarness({ sandboxConfig: { workDir: '/tmp/agent-work' }, harnesses: [...] });
// after
await prepareSandboxForHarness({ sandboxConfig: { workDir: 'agent-work' }, harnesses: [...] });

Defensive patterns

Strategy: validation

Validate before calling

if (path.posix.isAbsolute(workDir)) throw new Error('workDir must be relative');

Type guard

function isRelativePosixPath(v: unknown): v is string { return typeof v === 'string' && v.length > 0 && !path.posix.isAbsolute(v); }

Try / catch

try { await prepareSandboxForHarness({ sandboxConfig: { workDir }, harnesses }); } catch (e) { if (e.message.includes('must be relative')) { workDir = workDir.replace(/^\//, ''); } else throw e; }

Prevention

Document that workDir is relative to the sandbox default working directory
Strip leading slashes when accepting paths from users
Write a small config validator for sandbox settings

When it happens

Trigger: Passing an absolute POSIX path like '/tmp/work' or '/home/user/project' as sandboxConfig.workDir to prepareSandboxForHarness or agent creation.

Common situations: Reusing a host filesystem path as the sandbox workDir; misreading the docs and thinking workDir is an absolute container path.

Related errors

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