{"record":{"id":"e823958af21796e9","repo":"google-gemini/gemini-cli","slug":"max-turns-exceeded","errorCode":"MAX_TURNS_EXCEEDED","errorMessage":"MAX_TURNS_EXCEEDED","messagePattern":"MAX_TURNS_EXCEEDED","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/src/agent/event-translator.ts","lineNumber":167,"sourceCode":"      handleError(event.value.error, state, out);\n      break;\n\n    case GeminiEventType.UserCancelled:\n      ensureStreamStart(state, out);\n      out.push(\n        makeEvent('agent_end', state, {\n          reason: 'aborted',\n        }),\n      );\n      break;\n\n    case GeminiEventType.MaxSessionTurns:\n      ensureStreamStart(state, out);\n      out.push(\n        makeEvent('agent_end', state, {\n          reason: 'max_turns',\n          data: {\n            code: 'MAX_TURNS_EXCEEDED',\n          },\n        }),\n      );\n      break;\n\n    case GeminiEventType.LoopDetected:\n      ensureStreamStart(state, out);\n      out.push(\n        makeEvent('error', state, {\n          status: 'INTERNAL',\n          message: 'Loop detected, stopping execution',\n          fatal: false,\n          _meta: { code: 'LOOP_DETECTED' },\n        }),\n      );\n      break;\n\n    case GeminiEventType.ContextWindowWillOverflow:","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agent/event-translator.ts#L149-L185","documentation":"MAX_TURNS_EXCEEDED is emitted as an agent_end event (reason 'max_turns') when the Gemini stream reports GeminiEventType.MaxSessionTurns. It is the protocol-level signal that the server-side agent loop hit its turn budget. It is a terminal-but-successful stream end, not a thrown exception in the translator.","triggerScenarios":"translateEvent() receives an event of type GeminiEventType.MaxSessionTurns from sendMessageStream -> pushes an agent_end event with data.code 'MAX_TURNS_EXCEEDED'.","commonSituations":"Long agentic tasks (multi-file refactors, deep debugging) where the model chains many tool calls; tight maxTurns config; a tool keeps failing so the model retries indefinitely until the server cap trips.","solutions":["Raise the turn budget: config.setMaxSessionTurns() / server-side policy.","Inspect prior tool_request/tool_response events to find where the loop stalled and fix the failing tool.","Re-prompt with a more specific task so fewer turns are needed."],"exampleFix":"// before\nconfig.setMaxSessionTurns(20);\n// after\nconfig.setMaxSessionTurns(80);","handlingStrategy":"validation","validationCode":"// before launching the agent\nconst max = config.getMaxSessionTurns();\nif (typeof max === 'number' && max >= 0 && max < expectedTurns) {\n  config.setMaxSessionTurns(Math.max(max, expectedTurns));\n}","typeGuard":"function isMaxTurnsData(data: unknown): data is { code: 'MAX_TURNS_EXCEEDED'; maxTurns: number; turnCount: number } {\n  return typeof data === 'object' && data !== null && (data as any).code === 'MAX_TURNS_EXCEEDED';\n}","tryCatchPattern":"// agent_end event with reason 'max_turns' is not thrown; handle in the stream consumer:\nfor await (const ev of session) {\n  if (ev.type === 'agent_end' && ev.reason === 'max_turns') { /* surface + retry with higher budget */ }\n}","preventionTips":["Size maxTurns to the task (multi-file edits need more turns).","Log turnCount vs maxTurns on agent_end to detect chronic under-budgeting."],"tags":["agent-loop","turn-budget","gemini","typescript"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}