{"record":{"id":"fe66f0a00246cbd5","repo":"vercel/ai","slug":"unable-to-resolve-sandbox-home-directory-result","errorCode":null,"errorMessage":"Unable to resolve sandbox HOME directory: ${result.stderr || result.stdout}","messagePattern":"Unable to resolve sandbox HOME directory: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/harness/src/utils/sandbox-home-dir.ts","lineNumber":17,"sourceCode":"import path from 'node:path';\nimport type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';\n\nexport async function resolveSandboxHomeDir({\n  sandbox,\n  abortSignal,\n}: {\n  sandbox: Experimental_SandboxSession;\n  abortSignal?: AbortSignal;\n}): Promise<string> {\n  const result = await sandbox.run({\n    command: 'printf \"%s\" \"$HOME\"',\n    abortSignal,\n  });\n  const homeDir = result.stdout.trim();\n  if (result.exitCode !== 0 || !homeDir || !path.posix.isAbsolute(homeDir)) {\n    throw new Error(\n      `Unable to resolve sandbox HOME directory: ${result.stderr || result.stdout}`,\n    );\n  }\n  return homeDir;\n}\n","sourceCodeStart":1,"sourceCodeEnd":23,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness/src/utils/sandbox-home-dir.ts#L1-L23","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nconst session = await createSandbox({ image: 'distroless' }); // HOME unset\nconst home = await resolveSandboxHomeDir({ sandbox: session }); // throws\n// after\nconst session = await createSandbox({ image: 'distroless', env: { HOME: '/root' } });\nconst home = await resolveSandboxHomeDir({ sandbox: session });","handlingStrategy":"validation","validationCode":"const probe = await sandbox.run({ command: 'printf \"%s\" \"$HOME\"' });\nconst home = probe.stdout.trim();\nif (probe.exitCode !== 0 || !home || !require('node:path').posix.isAbsolute(home)) {\n  throw new Error(`Sandbox HOME invalid: ${JSON.stringify(home)}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const home = await resolveSandboxHomeDir({ sandbox });\n} catch (error) {\n  if (/Unable to resolve sandbox HOME/.test((error as Error).message)) {\n    return '/root'; // safe POSIX fallback\n  }\n  throw error;\n}","preventionTips":["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."],"tags":["sandbox","home-directory","environment","harness"],"backgroundTag":"missing-env-var","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}