vercel/ai · error · Error

Unable to resolve sandbox HOME directory: ${result.stderr ||

Error message

Unable to resolve sandbox HOME directory: ${result.stderr || result.stdout}

What it means

Thrown by resolveSandboxHomeDir in packages/harness/src/utils/sandbox-home-dir.ts when the `printf "%s" "$HOME"` probe fails: the command exits non-zero, produces empty output, or returns a non-absolute POSIX path. The harness needs the sandbox user's HOME directory to resolve home-relative paths, and without a valid absolute HOME it cannot proceed safely.

Source

Thrown at packages/harness/src/utils/sandbox-home-dir.ts:17

import path from 'node:path';
import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';

export async function resolveSandboxHomeDir({
  sandbox,
  abortSignal,
}: {
  sandbox: Experimental_SandboxSession;
  abortSignal?: AbortSignal;
}): Promise<string> {
  const result = await sandbox.run({
    command: 'printf "%s" "$HOME"',
    abortSignal,
  });
  const homeDir = result.stdout.trim();
  if (result.exitCode !== 0 || !homeDir || !path.posix.isAbsolute(homeDir)) {
    throw new Error(
      `Unable to resolve sandbox HOME directory: ${result.stderr || result.stdout}`,
    );
  }
  return homeDir;
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Ensure the sandbox environment defines HOME as an absolute POSIX path (e.g. set ENV HOME=/root in the image).
Run the sandbox as a user that has a valid home directory.
Manually run `printf "%s" "$HOME"` in the sandbox to inspect what is returned.
Use a POSIX (Linux) sandbox image rather than a Windows-based runtime.

Example fix

// before
const session = await createSandbox({ image: 'distroless' }); // HOME unset
const home = await resolveSandboxHomeDir({ sandbox: session }); // throws
// after
const session = await createSandbox({ image: 'distroless', env: { HOME: '/root' } });
const home = await resolveSandboxHomeDir({ sandbox: session });

Defensive patterns

Strategy: validation

Validate before calling

const probe = await sandbox.run({ command: 'printf "%s" "$HOME"' });
const home = probe.stdout.trim();
if (probe.exitCode !== 0 || !home || !require('node:path').posix.isAbsolute(home)) {
  throw new Error(`Sandbox HOME invalid: ${JSON.stringify(home)}`);
}

Try / catch

try {
  const home = await resolveSandboxHomeDir({ sandbox });
} catch (error) {
  if (/Unable to resolve sandbox HOME/.test((error as Error).message)) {
    return '/root'; // safe POSIX fallback
  }
  throw error;
}

Prevention

Set HOME explicitly in the sandbox image/env (e.g. HOME=/root).
Run the sandbox as a user with a valid home directory.
Avoid distroless/minimal images without HOME configured.
Use Linux images so HOME is a POSIX absolute path.

When it happens

Trigger: Calling resolveSandboxHomeDir (directly or via sandboxHomeDir/homeDir helpers) against a sandbox where `$HOME` is unset or empty, the shell exits non-zero, or HOME is relative/non-POSIX (e.g. Windows-style paths).

Common situations: Minimal container images with no HOME env var; sandboxes running as a user without a passwd entry; custom sandbox `run` implementations corrupting output; Windows sandboxes with `C:\Users\...` style HOME.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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