micro/go-micro · critical

agent %s checkpoint save: %w

Error message

agent %s checkpoint save: %w

What it means

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.

Source

Thrown at agent/checkpoint.go:52

		run = *existing
		run.Status = "running"
		run.State.Stage = agentAskStep
		if len(run.Steps) == 0 {
			run.Steps = []flow.StepRecord{{Name: agentAskStep}}
		}
		run.Steps[0].Status = "in_progress"
		run.Steps[0].Error = ""
		run.Steps[0].Result = ""
	}
	return run
}

func (a *agentImpl) saveRun(ctx context.Context, run flow.Run) error {
	if a.opts.Checkpoint == nil {
		return nil
	}
	if err := a.opts.Checkpoint.Save(ctx, run); err != nil {
		return fmt.Errorf("agent %s checkpoint save: %w", a.opts.Name, err)
	}
	if info, ok := ai.RunInfoFrom(ctx); ok {
		stage := run.State.Stage
		if stage == "" && len(run.Steps) > 0 {
			stage = run.Steps[0].Name
		}
		a.recordTimelineEvent(ctx, RunEvent{
			Time: time.Now(), RunID: info.RunID, ParentID: info.ParentID, Agent: info.Agent,
			Kind: "checkpoint", Name: stage, Status: run.Status,
		})
	}
	return nil
}

// Resume returns the response for a checkpointed agent run. Completed runs are
// returned from the checkpoint without calling the model or replaying tool
// calls; failed or in-progress runs continue from the saved input message.
func Resume(ctx context.Context, ag Agent, runID string) (*Response, error) {

View on GitHub (pinned to 24529f1404)

Solutions

1. Inspect errors.Unwrap(err) for the backend-specific cause
2. Verify the checkpoint backend (DB/Redis/file path) is reachable and writable
3. Check credentials and quotas for the checkpoint store
4. Test Save in isolation with a small run payload to rule out size limits
5. Add retries/circuit-breaking around the checkpoint store if it is flaky

Example fix

// before
resp, err := ag.Ask(ctx, msg)
// agent %s checkpoint save: dial tcp 10.0.0.5:6379: connect refused
// after
if err := checkpointStore.Ping(ctx); err != nil {
    log.Fatalf("checkpoint backend unavailable: %v", err)
}
resp, err := ag.Ask(ctx, msg)

// verify checkpoint backend before running the agent
if err := cpStore.Ping(ctx); err != nil {
    return fmt.Errorf("checkpoint backend unreachable: %w", err)
}

resp, err := ag.Ask(ctx, msg)
if err != nil && strings.Contains(err.Error(), "checkpoint save") {
    if ue := errors.Unwrap(err); ue != nil { log.Printf("save root cause: %v", ue) }
    // retry with backoff; or fail over to a replica store
}

When it happens

Trigger: 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.

Common situations: Redis/S3/DB checkpoint store down or credentials expired, disk quota exceeded, misconfigured checkpoint backend in Options, network partitions between agent and durable store.

Related errors

• %w; additionally failed to checkpoint failed run: %v
• flow %s checkpoint save: %w
• agent: ResumeStreamAsk unsupported by implementation
• agent: ResumeStreamAsk requires a checkpoint
• agent: checkpointed run not found

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/ce18d9da3f207040. Report an issue: GitHub.