google-gemini/gemini-cli · error · FatalSandboxError

LXC container '${containerName}' not found. Create one with:

Error message

LXC container '${containerName}' not found. Create one with: lxc launch ubuntu:24.04 ${containerName}

What it means

Thrown when `lxc list` succeeded and returned JSON, but no container with the expected name was found in the parsed list. The container must exist before it can be used as a sandbox. The message gives the exact creation command.

Source

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

        .filter(
          (item): item is Record<string, unknown> =>
            item !== null &&
            typeof item === 'object' &&
            'name' in item &&
            'status' in item,
        )
        .map((item) => ({
          name: String(item['name']),
          status: String(item['status']),
        }));
    }
  } catch {
    containers = [];
  }

  const container = containers.find((c) => c.name === containerName);
  if (!container) {
    throw new FatalSandboxError(
      `LXC container '${containerName}' not found. ` +
        `Create one with: lxc launch ubuntu:24.04 ${containerName}`,
    );
  }
  if (container.status.toLowerCase() !== 'running') {
    throw new FatalSandboxError(
      `LXC container '${containerName}' is not running (current status: ${container.status}). ` +
        `Start it with: lxc start ${containerName}`,
    );
  }

  const devicesToRemove: string[] = [];
  const removeDevices = () => {
    for (const deviceName of devicesToRemove) {
      try {
        spawnSync(
          'lxc',
          ['config', 'device', 'remove', containerName, deviceName],

View on GitHub (pinned to 5024443c72)

Solutions

Create the container with the exact name: `lxc launch ubuntu:24.04 <containerName>`.
List existing containers (`lxc list`) and either match the config name to one of them or rename the container.
Set config.containerName (or the equivalent setting) to the name of an existing container.

Example fix

// before: container 'gemini-sandbox' does not exist
// config.containerName = 'gemini-sandbox'

// after
// lxc launch ubuntu:24.04 gemini-sandbox

Defensive patterns

Strategy: validation

Validate before calling

const { execSync } = require('child_process');
function ensureContainerExists(name) {
  const out = execSync(`lxc list ${name} --format=json`, {encoding:'utf8'});
  const list = JSON.parse(out);
  if (!list.some(c => c.name === name)) {
    execSync(`lxc launch ubuntu:24.04 ${name}`, {stdio:'inherit'});
  }
}

Prevention

Provision the named container in your setup script.
Keep the configured containerName consistent across environments.

When it happens

Trigger: containers.find((c) => c.name === containerName) returns undefined after a successful lxc list query. Container was never created, was deleted, or containerName in config differs from what exists.

Common situations: First use of the LXC sandbox without provisioning the container. containerName changed in config. Container was removed by a cleanup script or another user. Typo in the configured container name.

Related errors

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