micro/go-micro · error

agent run %s not found

Error message

agent run %s not found

What it means

This error is returned by agent.Resume when the checkpoint store has no record for the given runID. The library looks up the run via opts.Checkpoint.Load and, when it reports ok=false, it cannot resume anything so it fails fast with the run ID in the message. It guards against resuming runs that were never started with a checkpoint store, already pruned, or addressed with a wrong ID.

Source

Thrown at agent/checkpoint.go:87

// calls; failed or in-progress runs continue from the saved input message.
func Resume(ctx context.Context, ag Agent, runID string) (*Response, error) {
	a, ok := ag.(*agentImpl)
	if !ok {
		return nil, fmt.Errorf("agent resume: unsupported agent implementation %T", ag)
	}
	return a.resume(ctx, runID)
}

func (a *agentImpl) resume(ctx context.Context, runID string) (*Response, error) {
	if a.opts.Checkpoint == nil {
		return nil, fmt.Errorf("agent %s has no checkpoint configured", a.opts.Name)
	}
	run, ok, err := a.opts.Checkpoint.Load(ctx, runID)
	if err != nil {
		return nil, err
	}
	if !ok {
		return nil, fmt.Errorf("agent run %s not found", runID)
	}
	if run.Status == "paused" {
		if run.State.Stage == agentInputStep {
			return nil, fmt.Errorf("agent run %s is input-required; resume with ResumeInput", runID)
		}
		run.Status = "running"
		run.State.Stage = agentAskStep
	}
	if run.Status == "done" {
		var resp Response
		if err := json.Unmarshal(run.State.Data, &resp); err != nil {
			return nil, fmt.Errorf("agent run %s response decode: %w", runID, err)
		}
		return &resp, nil
	}
	if terminalAgentRunStatus(run.Status) {
		return nil, fmt.Errorf("agent run %s is terminal with status %q", runID, run.Status)
	}

View on GitHub (pinned to 24529f1404)

Solutions

1. Verify the runID you pass to agent.Resume matches the ID returned by the original agent run and exists in the same checkpoint store used when the run started.
2. Confirm the agent was constructed with the same Checkpoint option (store implementation and connection) as when the run was created; re-create runs that were persisted to a different backend.
3. List pending runs via the checkpoint store's List (or agent's pending listing) to find valid resumable IDs.
4. Re-run the agent from scratch if the checkpoint is gone; there is nothing to resume.

Example fix

// before
resp, err := agent.Resume(ctx, ag, "run-123") // store actually has "run-abc"
// after
runID := respFromOriginalRun.ID // keep the real run ID from when the run started
resp, err := agent.Resume(ctx, ag, runID)

run, ok, err := ckpt.Load(ctx, runID)
if err != nil { return err }
if !ok { return fmt.Errorf("run %s missing from checkpoint store", runID) }
_, err = agent.Resume(ctx, ag, runID)

resp, err := agent.Resume(ctx, ag, runID)
if err != nil {
    if strings.Contains(err.Error(), "not found") {
        // fall back to starting a new run
        resp, err = ag.Run(ctx, message)
    }
}

When it happens

Trigger: Calling agent.Resume(ctx, ag, runID) with a runID that was never saved (agent not created with a Checkpoint option), an expired/purged checkpoint entry, or a typo'd/stale run ID from a different store or process.

Common situations: Restarting a service against a different (or in-memory) checkpoint backend than the one that saved the run; TTL-based checkpoint stores evicting old runs; passing a parent/tracing ID instead of the agent run ID; resuming after the run was manually deleted.

Related errors

• agent: ResumeStreamAsk unsupported by implementation
• agent: ResumeStreamAsk requires a checkpoint
• agent: checkpointed run not found
• agent: checkpointed run is terminal with status
• agent: checkpointed run is input-required; resume with Resum

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