{"record":{"id":"e0d6a1d885287b68","repo":"charmbracelet/crush","slug":"agent-run-failed-s","errorCode":null,"errorMessage":"agent run failed: %s","messagePattern":"agent run failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cmd/run.go","lineNumber":407,"sourceCode":"\t\t// mid-turn on finish.reason == tool_use.\n\t\t//\n\t\t// Correlation:\n\t\t//   - if we minted a RunID for this SendMessage, only the\n\t\t//     event whose RunID matches is ours; any other turn\n\t\t//     finishing first on the same session (busy-session\n\t\t//     queue path) must be ignored.\n\t\t//   - if we have no RunID (older server, tests), fall back\n\t\t//     to SessionID matching.\n\t\tif s.runID != \"\" {\n\t\t\tif e.Payload.RunID != s.runID {\n\t\t\t\treturn false, nil\n\t\t\t}\n\t\t} else if e.Payload.SessionID != s.sessionID {\n\t\t\treturn false, nil\n\t\t}\n\t\tstop()\n\t\tif e.Payload.Error != \"\" && !e.Payload.Cancelled {\n\t\t\treturn true, fmt.Errorf(\"agent run failed: %s\", e.Payload.Error)\n\t\t}\n\t\t// Reconcile stdout against the authoritative final\n\t\t// assistant text carried in the event. The pubsub fan-in\n\t\t// does not serialize publishes across upstream brokers, so\n\t\t// the final message event may not have reached this loop\n\t\t// yet; the embedded Text field is the backstop that\n\t\t// guarantees the full final text always appears on stdout.\n\t\tif e.Payload.MessageID != \"\" {\n\t\t\tfull := e.Payload.Text\n\t\t\treadBytes := s.read[e.Payload.MessageID]\n\t\t\tif readBytes < len(full) {\n\t\t\t\ttail := full[readBytes:]\n\t\t\t\tif readBytes == 0 {\n\t\t\t\t\ttail = strings.TrimLeft(tail, \" \\t\")\n\t\t\t\t}\n\t\t\t\tif s.printed || strings.TrimSpace(tail) != \"\" {\n\t\t\t\t\ts.printed = true\n\t\t\t\t\tfmt.Fprint(s.out, tail)","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/charmbracelet/crush/blob/7944b8e52225d8805e31eacbf7ef24856b0dfb7a/internal/cmd/run.go#L389-L425","documentation":"When a RunComplete event arrives for this session and its Payload.Error is non-empty and not a cancellation, the stream stops and surfaces the agent-side failure text verbatim via this error.","triggerScenarios":"Agent finished a run with an error: LLM provider returned an API error (auth, rate limit, overloaded), tool execution panicked/errored fatally, or the model request failed mid-run. The error string from the event is embedded.","commonSituations":"Expired/invalid API key; provider 429/5xx during long runs; context window exceeded by a huge prompt; a bash/edit tool returned a fatal error the agent surfaced as a run failure.","solutions":["Read the embedded payload error text for the true cause","Re-check provider API key and quota/rate limits","Retry — transient provider 5xx/overloaded errors often clear","Reduce prompt size or split the task if hitting context/token limits"],"exampleFix":"// before: retry immediately with no discrimination\nc.SendMessage(ctx, ws.ID, sess.ID, runID, prompt)\n// after: retry once on transient provider failure\nif err := c.SendMessage(ctx, ws.ID, sess.ID, runID, prompt); err != nil {\n\tif strings.Contains(err.Error(), \"overloaded\") || strings.Contains(err.Error(), \"429\") {\n\t\ttime.Sleep(5 * time.Second)\n\t\terr = c.SendMessage(ctx, ws.ID, sess.ID, runID, prompt)\n\t}\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to send message: %w\", err)\n\t}\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if e.Payload.Error != \"\" && !e.Payload.Cancelled {\n\terr := fmt.Errorf(\"agent run failed: %s\", e.Payload.Error)\n\tif strings.Contains(e.Payload.Error, \"rate limit\") || strings.Contains(e.Payload.Error, \"overloaded\") {\n\t\t// transient: schedule retry with backoff\n\t}\n\treturn true, err\n}","preventionTips":["Monitor provider quota and rotate/refresh API keys in CI","Add retry-with-backoff at the orchestration level for transient provider errors","Keep prompts within the model's context window to avoid hard failures"],"tags":["go","agent","llm","provider-error"],"backgroundTag":"llm-provider-run-failed","analyzedSha":"7944b8e52225d8805e31eacbf7ef24856b0dfb7a","analyzedAt":"2026-08-29T12:48:59.079Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}