google-gemini/gemini-cli · error · FatalSandboxError

Failed to query LXC container '${containerName}': ${err inst

Error message

Failed to query LXC container '${containerName}': ${err instanceof Error ? err.message : String(err)}. Make sure LXC/LXD is installed and '${containerName}' container exists. Create one with: lxc launch ubuntu:24.04 ${containerName}

What it means

Thrown when the `lxc list <containerName> --format=json` command fails entirely (the execFileAsync call rejects). This indicates LXC/LXD tooling is not installed, not on PATH, the daemon (lxd) is not running, or the user lacks permission to invoke lxc. The message embeds the underlying error and a remediation command.

Source

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

): Promise<number> {
  const containerName = config.image || 'gemini-sandbox';
  const workdir = path.resolve(process.cwd());

  debugLogger.log(
    `starting lxc sandbox (container: ${containerName}, workdir: ${workdir}) ...`,
  );

  // Verify the container exists and is running.
  let listOutput: string;
  try {
    const { stdout } = await execFileAsync('lxc', [
      'list',
      containerName,
      '--format=json',
    ]);
    listOutput = stdout.trim();
  } catch (err) {
    throw new FatalSandboxError(
      `Failed to query LXC container '${containerName}': ${err instanceof Error ? err.message : String(err)}. ` +
        `Make sure LXC/LXD is installed and '${containerName}' container exists. ` +
        `Create one with: lxc launch ubuntu:24.04 ${containerName}`,
    );
  }

  let containers: Array<{ name: string; status: string }> = [];
  try {
    const parsed: unknown = JSON.parse(listOutput);
    if (Array.isArray(parsed)) {
      containers = parsed
        .filter(
          (item): item is Record<string, unknown> =>
            item !== null &&
            typeof item === 'object' &&
            'name' in item &&
            'status' in item,
        )

View on GitHub (pinned to 5024443c72)

Solutions

Install LXD and initialize: `sudo apt install lxd && lxd init` (or `snap install lxd`).
Confirm `lxc list` works as your user; add yourself to the lxd group if needed (`sudo usermod -aG lxd $USER` then re-login).
Create the expected container: `lxc launch ubuntu:24.04 <containerName>`.
If you did not intend to use the LXC backend, switch the sandbox configuration to Docker/podman.

Example fix

// before: LXC backend selected but lxd not installed
// config.sandboxType = 'lxc'

// after: install + create container
// sudo snap install lxd
// lxd init --auto
// lxc launch ubuntu:24.04 gemini-sandbox

Defensive patterns

Strategy: validation

Validate before calling

const { execSync } = require('child_process');
function ensureLxcAvailable() {
  try {
    execSync('lxc --version', {stdio:'pipe'});
    execSync('lxc list --format=json', {stdio:'pipe'});
  } catch {
    throw new Error('LXC/LXD not available. Install lxd (`sudo snap install lxd`) and run `lxd init`.');
  }
}

Try / catch

try {
  await runLxcSandbox(config);
} catch (e) {
  if (e instanceof FatalSandboxError && /Failed to query LXC container/.test(e.message)) {
    // guide the user to install LXD or switch backend
  } else throw e;
}

Prevention

Add an environment preflight that checks `lxc --version` before selecting the LXC backend.
Ensure the running user has lxd permissions.

When it happens

Trigger: execFileAsync('lxc', ['list', containerName, '--format=json']) rejects — lxc binary missing, lxd daemon not initialized (`lxd init` not run), snap permission issue, or LXC not installed at all.

Common situations: Fresh OS install without LXD. User installed LXC but not LXD, or vice versa. snap-based lxc requires the user to be in the lxd group or to use `sudo`. lxd daemon stopped. Wrong sandbox backend selected (LXC) when Docker was intended.

Related errors

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