{"record":{"id":"ce18d9da3f207040","repo":"micro/go-micro","slug":"agent-s-checkpoint-save-w","errorCode":null,"errorMessage":"agent %s checkpoint save: %w","messagePattern":"agent (.+?) checkpoint save: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"agent/checkpoint.go","lineNumber":52,"sourceCode":"\t\trun = *existing\n\t\trun.Status = \"running\"\n\t\trun.State.Stage = agentAskStep\n\t\tif len(run.Steps) == 0 {\n\t\t\trun.Steps = []flow.StepRecord{{Name: agentAskStep}}\n\t\t}\n\t\trun.Steps[0].Status = \"in_progress\"\n\t\trun.Steps[0].Error = \"\"\n\t\trun.Steps[0].Result = \"\"\n\t}\n\treturn run\n}\n\nfunc (a *agentImpl) saveRun(ctx context.Context, run flow.Run) error {\n\tif a.opts.Checkpoint == nil {\n\t\treturn nil\n\t}\n\tif err := a.opts.Checkpoint.Save(ctx, run); err != nil {\n\t\treturn fmt.Errorf(\"agent %s checkpoint save: %w\", a.opts.Name, err)\n\t}\n\tif info, ok := ai.RunInfoFrom(ctx); ok {\n\t\tstage := run.State.Stage\n\t\tif stage == \"\" && len(run.Steps) > 0 {\n\t\t\tstage = run.Steps[0].Name\n\t\t}\n\t\ta.recordTimelineEvent(ctx, RunEvent{\n\t\t\tTime: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent,\n\t\t\tKind: \"checkpoint\", Name: stage, Status: run.Status,\n\t\t})\n\t}\n\treturn nil\n}\n\n// Resume returns the response for a checkpointed agent run. Completed runs are\n// returned from the checkpoint without calling the model or replaying tool\n// calls; failed or in-progress runs continue from the saved input message.\nfunc Resume(ctx context.Context, ag Agent, runID string) (*Response, error) {","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/micro/go-micro/blob/24529f140421a11a33b6999ab7944f2021cfd69c/agent/checkpoint.go#L34-L70","documentation":"agentImpl.saveRun (agent/checkpoint.go:52) persists each run via the configured Checkpoint store. If Checkpoint.Save fails (storage outage, serialization problem, permissions), the error is wrapped as 'agent %s checkpoint save: %w' and propagates to the caller of askLocked or the run loop, aborting the current step since durability cannot be guaranteed.","triggerScenarios":"Any run execution (askLocked, pause/save points) where opts.Checkpoint.Save(ctx, run) returns an error — checkpoint backend unreachable, disk full, write permission denied, or an oversized run payload the store rejects.","commonSituations":"Redis/S3/DB checkpoint store down or credentials expired, disk quota exceeded, misconfigured checkpoint backend in Options, network partitions between agent and durable store.","solutions":["Inspect errors.Unwrap(err) for the backend-specific cause","Verify the checkpoint backend (DB/Redis/file path) is reachable and writable","Check credentials and quotas for the checkpoint store","Test Save in isolation with a small run payload to rule out size limits","Add retries/circuit-breaking around the checkpoint store if it is flaky"],"exampleFix":"// before\nresp, err := ag.Ask(ctx, msg)\n// agent %s checkpoint save: dial tcp 10.0.0.5:6379: connect refused\n// after\nif err := checkpointStore.Ping(ctx); err != nil {\n    log.Fatalf(\"checkpoint backend unavailable: %v\", err)\n}\nresp, err := ag.Ask(ctx, msg)\n","handlingStrategy":"retry","validationCode":"// verify checkpoint backend before running the agent\nif err := cpStore.Ping(ctx); err != nil {\n    return fmt.Errorf(\"checkpoint backend unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"resp, err := ag.Ask(ctx, msg)\nif err != nil && strings.Contains(err.Error(), \"checkpoint save\") {\n    if ue := errors.Unwrap(err); ue != nil { log.Printf(\"save root cause: %v\", ue) }\n    // retry with backoff; or fail over to a replica store\n}","preventionTips":["Monitor and alert on checkpoint store health","Provision adequate disk/quota for the store","Test checkpoint writes in CI with the real backend type","Use a replicated/highly available checkpoint store"],"tags":["go","checkpoint","persistence","storage"],"backgroundTag":"checkpoint-save-failed","analyzedSha":"24529f140421a11a33b6999ab7944f2021cfd69c","analyzedAt":"2026-09-01T02:52:24.923Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}