{"record":{"id":"68fd5adecf801335","repo":"google-gemini/gemini-cli","slug":"reached-max-session-turns-for-this-session-increa","errorCode":null,"errorMessage":"Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.","messagePattern":"Reached max session turns for this session\\. Increase the number of turns by specifying maxSessionTurns in settings\\.json\\.","errorType":"exception","errorClass":"FatalTurnLimitedError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/nonInteractiveCliAgentSession.ts","lineNumber":650,"sourceCode":"                type: JsonStreamEventType.ERROR,\n                timestamp: new Date().toISOString(),\n                severity,\n                message: stripAnsi(event.message),\n              });\n            }\n            warnings.push(event.message);\n            break;\n          }\n          case 'agent_end': {\n            if (event.reason === 'aborted') {\n              throw new FatalCancellationError('Operation cancelled.');\n            } else if (event.reason === 'max_turns') {\n              const isConfiguredTurnLimit =\n                typeof event.data?.['maxTurns'] === 'number' ||\n                typeof event.data?.['turnCount'] === 'number';\n\n              if (isConfiguredTurnLimit) {\n                throw new FatalTurnLimitedError(\n                  'Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.',\n                );\n              } else if (streamFormatter) {\n                streamFormatter.emitEvent({\n                  type: JsonStreamEventType.ERROR,\n                  timestamp: new Date().toISOString(),\n                  severity: 'error',\n                  message: 'Maximum session turns exceeded',\n                });\n              }\n            }\n\n            const stopMessage =\n              typeof event.data?.['message'] === 'string'\n                ? event.data['message']\n                : '';\n            if (stopMessage && config.getOutputFormat() === OutputFormat.TEXT) {\n              process.stderr.write(`Agent execution stopped: ${stopMessage}\\n`);","sourceCodeStart":632,"sourceCodeEnd":668,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/cli/src/nonInteractiveCliAgentSession.ts#L632-L668","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before — ~/.gemini/settings.json\n{ \"maxSessionTurns\": 10 }\n// after\n{ \"maxSessionTurns\": 40 }","handlingStrategy":"validation","validationCode":"function adequateTurnLimit(taskComplexity: 'low' | 'med' | 'high'): number {\n  return taskComplexity === 'high' ? 60 : taskComplexity === 'med' ? 30 : 15;\n}\n// set in settings.json: \"maxSessionTurns\": adequateTurnLimit('high')","typeGuard":"function isConfiguredTurnLimit(data?: unknown): boolean {\n  return typeof (data as { maxTurns?: unknown })?.maxTurns === 'number' ||\n    typeof (data as { turnCount?: unknown })?.turnCount === 'number';\n}","tryCatchPattern":"try {\n  await runAgentSession(input);\n} catch (e) {\n  if (e instanceof FatalTurnLimitedError) {\n    // exit code 53: raise maxSessionTurns in settings.json and re-run\n    console.error(e.message);\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["agent-session","turns","configuration","limits","non-interactive"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}