google-gemini/gemini-cli · error · FatalConfigError

Invalid telemetry configuration: ${err.message}.

Error message

Invalid telemetry configuration: ${err.message}.

What it means

Wraps a `FatalConfigError` raised by `resolveTelemetrySettings` (called with `process.env` and `settings.telemetry`). It rethrows a new `FatalConfigError` with a `Invalid telemetry configuration:` prefix, preserving the inner message. The inner failure typically stems from an invalid endpoint URL, malformed sample rate, disabled-but-configured output, or an unrecognized exporter.

Source

Thrown at packages/cli/src/config/config.ts:774

  // Force approval mode to default if the folder is not trusted.
  if (!trustedFolder && approvalMode !== ApprovalMode.DEFAULT) {
    debugLogger.warn(
      `Approval mode overridden to "default" because the current folder is not trusted.`,
    );
    approvalMode = ApprovalMode.DEFAULT;
  }

  let telemetrySettings;
  try {
    telemetrySettings = await resolveTelemetrySettings({
      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
      env: process.env as unknown as Record<string, string | undefined>,
      settings: settings.telemetry,
    });
  } catch (err) {
    if (err instanceof FatalConfigError) {
      throw new FatalConfigError(
        `Invalid telemetry configuration: ${err.message}.`,
      );
    }
    throw err;
  }

  // -p/--prompt forces non-interactive (headless) mode
  // -i/--prompt-interactive forces interactive mode with an initial prompt
  const interactive =
    !!argv.promptInteractive ||
    !!argv.acp ||
    !!argv.experimentalAcp ||
    (!isHeadlessMode({ prompt: argv.prompt, query: argv.query }) &&
      !argv.isCommand);

  const allowedTools = argv.allowedTools || settings.tools?.allowed || [];

  const isAcpMode = !!argv.acp || !!argv.experimentalAcp;

View on GitHub (pinned to 5024443c72)

Solutions

  1. Read the inner message (everything after `Invalid telemetry configuration:`) for the specific failure.
  2. Validate `telemetry.endpoint` is a full `http(s)://host[:port]` URL.
  3. Confirm `telemetry.enabled` is consistent with the other fields (e.g. not disabled while endpoints are set).
  4. Clear the offending `OTEL_*` env var to fall back to defaults.

Example fix

// before (settings.json)
{ "telemetry": { "endpoint": "localhost:4317" } }
// after
{ "telemetry": { "endpoint": "http://localhost:4317" } }
Defensive patterns

Strategy: try-catch

Validate before calling

function isHttpUrl(v: unknown): v is string {
  return typeof v === 'string' && /^https?:\/\/.+/.test(v);
}
if (settings.telemetry?.endpoint && !isHttpUrl(settings.telemetry.endpoint)) {
  throw new Error('telemetry.endpoint must be a full http(s):// URL');
}

Type guard

function isTelemetrySettings(v: unknown): boolean {
  if (typeof v !== 'object' || v === null) return true;
  const t = v as { endpoint?: unknown; sampleRate?: unknown };
  if (t.endpoint !== undefined && !/^https?:\/\/.+/.test(String(t.endpoint))) return false;
  if (t.sampleRate !== undefined && (typeof t.sampleRate !== 'number' || t.sampleRate < 0 || t.sampleRate > 1)) return false;
  return true;
}

Try / catch

try {
  telemetrySettings = await resolveTelemetrySettings({ env, settings: settings.telemetry });
} catch (err) {
  if (err instanceof FatalConfigError) {
    throw new FatalConfigError(`Invalid telemetry configuration: ${err.message}.`);
  }
  throw err;
}

Prevention

When it happens

Trigger: Setting `telemetry.endpoint` to a non-URL string; an unrecognized `telemetry.exporter` value; a sample rate outside `[0,1]`; an env var like `OTEL_EXPORTER_OTLP_ENDPOINT` with an invalid protocol.

Common situations: Mistyped endpoint in settings.json; env var drift from another OTLP collector; CI environments that set `OTEL_*` vars globally; switching from a dev collector to a prod one with a typo.

Related errors

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