'HarnessAgent: `sandboxConfig.workDir` must not be empty.'

Error message

'HarnessAgent: `sandboxConfig.workDir` must not be empty.'

What it means

`normalizeSandboxWorkDir` rejects an empty `sandboxConfig.workDir` string. A work directory must be a non-empty path for the sandbox to know where to operate; an empty string is never a valid target, so validation fails fast with this error (an adjacent check also rejects NUL bytes).

Source

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

};

export function validateSandboxBootstrapSettings(
  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 === '.' ||

View on GitHub (pinned to 69428b1f8b)

Solutions

Set `sandboxConfig.workDir` to a non-empty absolute path (e.g. '/workspace').
If the value comes from an env var, default or validate it before constructing the agent (e.g. `process.env.SANDBOX_WORK_DIR ?? '/workspace'`).
Omit `workDir` entirely if it is optional and you have no value, rather than passing ''.

Example fix

// before
new HarnessAgent({ sandboxConfig: { workDir: process.env.SANDBOX_WORK_DIR ?? '' } });

// after
const workDir = process.env.SANDBOX_WORK_DIR;
if (!workDir) throw new Error('SANDBOX_WORK_DIR is required');
new HarnessAgent({ sandboxConfig: { workDir } });

Defensive patterns

Strategy: validation

Validate before calling

if (typeof workDir !== 'string' || workDir.length === 0) {
  throw new Error('sandboxConfig.workDir must be a non-empty string.');
}

Type guard

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

Try / catch

try {
  const agent = new HarnessAgent({ sandboxConfig: { workDir } });
} catch (e) {
  if (e instanceof Error && e.message.includes('workDir')) {
    // supply a valid non-empty path or omit workDir
  }
  throw e;
}

Prevention

Validate env-var-backed config values before constructing the agent.
Prefer undefined over '' when a value is missing.
Fail fast at config-load time with a clear message naming the env var.

When it happens

Trigger: Passing `sandboxConfig.workDir: ''` (or a variable that resolves to an empty string) when constructing a HarnessAgent or calling code that normalizes the work dir (e.g. the `workDir` getter path).

Common situations: Reading workDir from an env var like `SANDBOX_WORK_DIR` that is unset/empty; template strings built from missing config; defaulting code that assigns '' instead of undefined.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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