What causes "agent: checkpointed run not found" in micro/go-micro?

Verify the runID exists in the configured Checkpoint store before resuming

agent: checkpointed run not found

Error message

agent: checkpointed run not found

What it means

The checkpoint store was consulted for the given runID but reported the run does not exist (Load returned ok=false). Resume cannot proceed without a persisted run state.

Source

Thrown at agent/stream.go:149

		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)
	}

	a.mu.Lock()
	defer a.mu.Unlock()
	if a.tools == nil {
		a.tools = ai.NewTools(a.opts.Registry, ai.ToolClient(a.opts.Client))
	}
	base := a.toolHandler()

View on GitHub (pinned to 24529f1404)

Solutions

Verify the runID exists in the configured Checkpoint store before resuming
Ensure the same checkpoint backend is used for the run's creation and the resume
Log/persist runIDs durably and check Load's ok flag in your own tooling

Example fix

// before
stream, err := agent.ResumeStreamAsk(ctx, ag, runID)
// after
if _, ok, _ := store.Load(ctx, runID); !ok {
    return fmt.Errorf("run %s not found", runID)
}
stream, err := agent.ResumeStreamAsk(ctx, ag, runID)

Defensive patterns

Strategy: validation

Validate before calling

run, ok, err := store.Load(ctx, runID)
if err != nil || !ok {
    return fmt.Errorf("run %q not found in checkpoint store", runID)
}

Try / catch

stream, err := agent.ResumeStreamAsk(ctx, ag, runID)
if err != nil && strings.Contains(err.Error(), "not found") {
    return startNewRun(ctx, ag) // runID is stale/unknown
}

Prevention

Persist runIDs in the same durable store used for checkpoints
Verify store configuration (DSN/bucket/path) matches across write and read paths
Check for TTL/cleanup policies that may evict runs before resume

When it happens

Trigger: Calling ResumeStreamAsk/ResumeStream with a runID that was never created, was created by a different checkpoint store/environment, or was deleted/expired from the store.

Common situations: Typo'd or stale runID; pointing at a different database/backend than the one that recorded the run; TTL/cleanup evicted the checkpoint; resuming after switching from in-memory to persistent store (or across processes with memory store).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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