What causes "agent: ResumeStreamAsk requires a checkpoint" in micro/go-micro?

Configure a checkpoint store when constructing the agent: agent.WithCheckpoint(store)

agent: ResumeStreamAsk requires a checkpoint

Error message

agent: ResumeStreamAsk requires a checkpoint

What it means

resumeWithStreamEvents requires agent Options.Checkpoint to be configured, since resuming a run needs a store to load its checkpoint from. When no checkpoint store is set, resume is impossible and this error is returned.

Source

Thrown at agent/stream.go:142

	if a.tools == nil {
		a.tools = ai.NewTools(a.opts.Registry, ai.ToolClient(a.opts.Client))
	}
	base := a.toolHandler()
	handler := func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
		_ = sendStreamEvent(ctx, events, &StreamEvent{Type: StreamEventToolStart, ToolCall: call})
		result := base(ctx, call)
		_ = sendStreamEvent(ctx, events, &StreamEvent{Type: StreamEventToolEnd, ToolCall: call, Result: result})
		return result
	}
	a.setupWithToolHandler(handler)
	defer a.setupWithToolHandler(nil)
	return a.askLocked(ctx, uuid.New().String(), message, a.parentRunID, nil, true)
}

func (a *agentImpl) resumeWithStreamEvents(ctx context.Context, runID string, events chan<- *StreamEvent) (*Response, error) {
	if a.opts.Checkpoint == nil {
		return nil, errors.New("agent: ResumeStreamAsk requires a checkpoint")
	}
	run, ok, err := a.opts.Checkpoint.Load(ctx, runID)
	if err != nil {
		return nil, err
	}
	if !ok {
		return nil, errors.New("agent: checkpointed run not found")
	}
	if run.Status == "done" {
		var resp Response
		if err := json.Unmarshal(run.State.Data, &resp); err != nil {
			return nil, err
		}
		return &resp, nil
	}
	if terminalAgentRunStatus(run.Status) {
		return nil, errors.New("agent: checkpointed run is terminal with status " + run.Status)
	}

View on GitHub (pinned to 24529f1404)

Solutions

Configure a checkpoint store when constructing the agent: agent.WithCheckpoint(store)
Verify the checkpoint store is wired in the environment (e.g. DB/file backend initialized)
Guard resume calls: only resume runs for agents known to have checkpointing enabled

Example fix

// before
ag := agent.New(client, registry)
stream, err := agent.ResumeStreamAsk(ctx, ag, runID)
// after
ag := agent.New(client, registry, agent.WithCheckpoint(store))
stream, err := agent.ResumeStreamAsk(ctx, ag, runID)

Defensive patterns

Strategy: validation

Validate before calling

if agentCheckpointStore == nil {
    return errors.New("agent not constructed with WithCheckpoint; resume unavailable")
}

Try / catch

stream, err := agent.ResumeStreamAsk(ctx, ag, runID)
if err != nil && strings.Contains(err.Error(), "requires a checkpoint") {
    return fmt.Errorf("enable checkpointing to resume runs")
}

Prevention

Always construct resumable agents with agent.WithCheckpoint(store)
Centralize agent construction so checkpoint config is never omitted
Add a startup assertion that the checkpoint store is non-nil when resume features are enabled

When it happens

Trigger: Calling ResumeStreamAsk (or ResumeStream) on an agent constructed without a Checkpoint option.

Common situations: Building the agent with agent.New(...) and forgetting the WithCheckpoint option; resuming across a config change that dropped the checkpoint store; default constructors that omit persistence.

Related errors

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