'HarnessAgent: `sandboxConfig.workDir` must not contain…

Error message

'HarnessAgent: `sandboxConfig.workDir` must not contain NUL.'

What it means

normalizeSandboxWorkDir validates the `sandboxConfig.workDir` string before it is used in sandbox shell commands. A NUL character ('\0') in a path is illegal on POSIX systems and would truncate the path or corrupt command execution, so the library rejects it eagerly with a clear message rather than failing obscurely later inside the sandbox.

Solutions

Inspect the workDir value (e.g. JSON.stringify it to reveal hidden chars) and remove the NUL character.
Sanitize input before passing it: workDir = workDir.replace(/\0/g, '').
If the path comes from a buffer or external source, decode it explicitly with Buffer.from(x, 'utf8').toString() and validate it first.

Example fix

// before
const workDir = rawBuffer.toString().split('\u0000')[0] + '\u0000rest';
// after
const workDir = rawBuffer.toString('utf8').split('\u0000')[0];

Defensive patterns

Strategy: validation

Validate before calling

function isValidWorkDir(w) { return typeof w === 'string' && w.length > 0 && !w.includes('\0'); }

Type guard

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

Try / catch

try { await prepareSandboxForHarness({ sandboxConfig: { workDir }, harnesses }); } catch (e) { if (e.message.includes('must not contain NUL')) { /* sanitize and retry */ } else throw e; }

Prevention

Sanitize any path derived from buffers or external input with replace(/\0/g, '')
Log paths with JSON.stringify to reveal hidden control characters
Validate config values at load time, before agent construction

When it happens

Trigger: Calling createAgent/prepareSandboxForHarness with sandboxConfig.workDir containing a '\0' character, e.g. from binary-parsed config, template strings built from buffers, or accidentally split multi-byte data.

Common situations: Config loaded from a binary or partially-corrupt file; building a path with String.fromCharCode(0) or a buffer slice; copy-pasted hidden control characters.

Related errors

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

Appendix: source

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

  settings: SandboxBootstrapSettings,
): void {
  if ((settings.onBootstrap == null) !== (settings.bootstrapHash == null)) {
    throw new Error(
      'HarnessAgent: `sandboxConfig.onBootstrap` and `sandboxConfig.bootstrapHash` must be provided together.',
    );
  }

  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('../')
  ) {

View on GitHub (pinned to 69428b1f8b)