google-gemini/gemini-cli · error · FatalConfigError

${errorMessages.join('\n')}\nPlease fix the configuration fi

Error message

${errorMessages.join('\n')}\nPlease fix the configuration file(s) and try again.

What it means

Thrown by the settings loader after merging system, user, and workspace settings.json files when at least one validation error has severity 'error'. It is a FatalConfigError (exit code 52). The message aggregates every fatal error as 'Error in <path>: <message>' so the offending file and reason are visible.

Source

Thrown at packages/cli/src/config/settings.ts:922

  const tempMergedSettings = mergeSettings(
    systemSettings,
    systemDefaultSettings,
    userSettings,
    workspaceSettings,
    isTrusted,
  );

  // loadEnvironment depends on settings so we have to create a temp version of
  // the settings to avoid a cycle
  loadEnvironment(tempMergedSettings, workspaceDir);

  // Check for any fatal errors before proceeding
  const fatalErrors = settingsErrors.filter((e) => e.severity === 'error');
  if (fatalErrors.length > 0) {
    const errorMessages = fatalErrors.map(
      (error) => `Error in ${error.path}: ${error.message}`,
    );
    throw new FatalConfigError(
      `${errorMessages.join('\n')}\nPlease fix the configuration file(s) and try again.`,
    );
  }

  const loadedSettings = new LoadedSettings(
    {
      path: systemSettingsPath,
      settings: systemSettings,
      originalSettings: systemOriginalSettings,
      rawJson: systemResult.rawJson,
      readOnly: true,
    },
    {
      path: systemDefaultsPath,
      settings: systemDefaultSettings,
      originalSettings: systemDefaultsOriginalSettings,
      rawJson: systemDefaultsResult.rawJson,
      readOnly: true,

View on GitHub (pinned to 5024443c72)

Solutions

1. Read the full message: each line names the exact file path and the validation message for that file.
2. Open the named settings.json and fix the specific field/value cited (correct types, valid enum values, valid JSON syntax).
3. Validate the file against the settings JSON schema (docs/schemas) or temporarily rename it to confirm it is the culprit.
4. Re-run the CLI to confirm no further fatal errors remain; warnings (severity !== 'error') do not block startup.

Example fix

// before — ~/.gemini/settings.json
{ "outputFormat": "jsom", "theme": "auto" }
// after
{ "outputFormat": "json", "theme": "auto" }

import Ajv from 'ajv';
import settingsSchema from './docs/schemas/settings.schema.json';

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(settingsSchema);

function validateSettingsFile(filePath: string): string[] {
  const json = JSON.parse(fs.readFileSync(filePath, 'utf8'));
  if (!validate(json)) {
    return (validate.errors || []).map((e) => `${e.instancePath} ${e.message}`);
  }
  return [];
}

function isSettingsShape(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null && !Array.isArray(v);
}

try {
  const settings = await loadSettings(...);
} catch (e) {
  if (e instanceof FatalConfigError) {
    // exit code 52: e.message lists each 'Error in <path>: <reason>'
    for (const line of e.message.split('\n')) console.error(line);
  }
  throw e;
}

When it happens

Trigger: loadSettings() runs schema/validation across the merged settings stack; settingsErrors contains entries whose .severity === 'error' (malformed JSON, schema violations, invalid enum values, type mismatches marked fatal).

Common situations: A typo or invalid field in ~/.gemini/settings.json or .gemini/settings.json (e.g. wrong output format, bad model name, unknown key at error severity); hand-editing the JSON and leaving a trailing comma or unquoted value; a settings schema change after an upgrade rejecting previously-tolerated keys.

Related errors

• Invalid approval mode: ${rawApprovalMode}. Valid values are:
• Invalid environment variable name: "${key}". Must contain on
• Invalid environment variable value for "${key}". Values cann
• Failed to parse inline agent card JSON for agent '${name}':
• Validation failed: ${formatZodError(result.error, 'Agent Def

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