google-gemini/gemini-cli · error · FatalSandboxError

Path '${from}' listed in SANDBOX_MOUNTS must be absolute

Error message

Path '${from}' listed in SANDBOX_MOUNTS must be absolute

What it means

Thrown while parsing the SANDBOX_MOUNTS environment variable when a mount source path (`from`) is not absolute. Docker volume mounts require absolute host paths, so a relative path is rejected before it can produce a confusing Docker error. The mount string is parsed as from:to:opts (colon-delimited).

Source

Thrown at packages/cli/src/utils/sandbox.ts:482

        args.push(
          '--env',
          `GOOGLE_APPLICATION_CREDENTIALS=${getContainerPath(adcFile)}`,
        );
      }
    }

    // mount paths listed in SANDBOX_MOUNTS
    if (process.env['SANDBOX_MOUNTS']) {
      for (let mount of process.env['SANDBOX_MOUNTS'].split(',')) {
        if (mount.trim()) {
          // parse mount as from:to:opts
          let [from, to, opts] = mount.trim().split(':');
          to = to || from; // default to mount at same path inside container
          opts = opts || 'ro'; // default to read-only
          mount = `${from}:${to}:${opts}`;
          // check that from path is absolute
          if (!path.isAbsolute(from)) {
            throw new FatalSandboxError(
              `Path '${from}' listed in SANDBOX_MOUNTS must be absolute`,
            );
          }
          // check that from path exists on host
          if (!fs.existsSync(from)) {
            throw new FatalSandboxError(
              `Missing mount path '${from}' listed in SANDBOX_MOUNTS`,
            );
          }
          debugLogger.log(`SANDBOX_MOUNTS: ${from} -> ${to} (${opts})`);
          args.push('--volume', mount);
        }
      }
    }

    // mount paths listed in config.allowedPaths
    if (config.allowedPaths) {
      for (const hostPath of config.allowedPaths) {

View on GitHub (pinned to 5024443c72)

Solutions

1. Prefix each `from` path with an absolute path, e.g. SANDBOX_MOUNTS=/home/me/project/data:/data:ro.
2. If scripting, expand with $(realpath ./data) or $PWD so the value is absolute at runtime.
3. Validate every entry in SANDBOX_MOUNTS resolves to an absolute path before launching the sandbox.

Example fix

// before
// SANDBOX_MOUNTS=./secrets:/secrets:ro

// after
// SANDBOX_MOUNTS=/home/me/secrets:/secrets:ro

const path = require('path');
function validateSandboxMounts(mountsStr) {
  for (const raw of (mountsStr || '').split(',')) {
    const m = raw.trim();
    if (!m) continue;
    const from = m.split(':')[0];
    if (!path.isAbsolute(from)) {
      throw new Error(`SANDBOX_MOUNTS entry '${from}' must be absolute`);
    }
  }
}

const isAbsoluteMountEntry = (entry) => {
  const from = entry.trim().split(':')[0];
  return typeof entry === 'string' && from.length > 0 && path.isAbsolute(from);
};

When it happens

Trigger: SANDBOX_MOUNTS contains an entry like `./data:/data:ro` or `relative/path` where the `from` segment fails path.isAbsolute().

Common situations: User sets SANDBOX_MOUNTS=$(pwd)/data:/data but the shell expansion is quoted oddly leaving a relative prefix. Copying a mount example from docs that used a relative path. Defining SANDBOX_MOUNTS in a .env file with a path intended to be relative to the project.

Related errors

• Missing mount path '${from}' listed in SANDBOX_MOUNTS
• SANDBOX_ENV must be a comma-separated list of key=value pair
• Cannot build sandbox using installed gemini binary; run `npm
• Security violation: The path "${trimmedPath}" is outside the
• Invalid sandbox command '${sandbox}'. Must be one of ${VALID

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/6da6f0625f1c8f4f. Report an issue: GitHub.