google-gemini/gemini-cli · error · FatalTurnLimitedError

Reached max session turns for this session. Increase the num

Error message

Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.

What it means

Thrown when agent_end has reason === 'max_turns' AND the event data carries a numeric maxTurns or turnCount (i.e. a configured, not default, limit). It is a FatalTurnLimitedError (exit code 53). The agent exhausted the configured maxSessionTurns and was halted.

Source

Thrown at packages/cli/src/nonInteractiveCliAgentSession.ts:650

                type: JsonStreamEventType.ERROR,
                timestamp: new Date().toISOString(),
                severity,
                message: stripAnsi(event.message),
              });
            }
            warnings.push(event.message);
            break;
          }
          case 'agent_end': {
            if (event.reason === 'aborted') {
              throw new FatalCancellationError('Operation cancelled.');
            } else if (event.reason === 'max_turns') {
              const isConfiguredTurnLimit =
                typeof event.data?.['maxTurns'] === 'number' ||
                typeof event.data?.['turnCount'] === 'number';

              if (isConfiguredTurnLimit) {
                throw new FatalTurnLimitedError(
                  'Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.',
                );
              } else if (streamFormatter) {
                streamFormatter.emitEvent({
                  type: JsonStreamEventType.ERROR,
                  timestamp: new Date().toISOString(),
                  severity: 'error',
                  message: 'Maximum session turns exceeded',
                });
              }
            }

            const stopMessage =
              typeof event.data?.['message'] === 'string'
                ? event.data['message']
                : '';
            if (stopMessage && config.getOutputFormat() === OutputFormat.TEXT) {
              process.stderr.write(`Agent execution stopped: ${stopMessage}\n`);

View on GitHub (pinned to 5024443c72)

Solutions

Increase maxSessionTurns in settings.json (the message names the exact key).
Re-run the session and resume from where it stopped.
If turns are being consumed by a loop, inspect the transcript to fix the repeating tool-call pattern before raising the limit.
For one-off needs, override the limit via the CLI flag/setting for that run only.

Example fix

// before — ~/.gemini/settings.json
{ "maxSessionTurns": 10 }
// after
{ "maxSessionTurns": 40 }

Defensive patterns

Strategy: validation

Validate before calling

function adequateTurnLimit(taskComplexity: 'low' | 'med' | 'high'): number {
  return taskComplexity === 'high' ? 60 : taskComplexity === 'med' ? 30 : 15;
}
// set in settings.json: "maxSessionTurns": adequateTurnLimit('high')

Type guard

function isConfiguredTurnLimit(data?: unknown): boolean {
  return typeof (data as { maxTurns?: unknown })?.maxTurns === 'number' ||
    typeof (data as { turnCount?: unknown })?.turnCount === 'number';
}

Try / catch

try {
  await runAgentSession(input);
} catch (e) {
  if (e instanceof FatalTurnLimitedError) {
    // exit code 53: raise maxSessionTurns in settings.json and re-run
    console.error(e.message);
  }
  throw e;
}

Prevention

Size maxSessionTurns to the task complexity; agentic/multi-tool tasks need more turns.
Investigate transcripts that hit the limit repeatedly — a tool-calling loop may be wasting budget.
Override the limit per-run for one-off complex tasks instead of lowering the global default.

When it happens

Trigger: The session reached the maxSessionTurns cap configured in settings.json (or passed via flags); event.data.maxTurns or event.data.turnCount is a number, so isConfiguredTurnLimit is true and the fatal error is thrown.

Common situations: A complex/agentic task needs more tool-calling rounds than the configured limit; maxSessionTurns was lowered for cost control; an infinite tool-calling loop burns through the budget.

Related errors

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