micro/go-micro · error

agent run %s response decode: %w

Error message

agent run %s response decode: %w

What it means

Returned when agent.Resume finds a completed ("done") run in the checkpoint and attempts to decode its stored response JSON into agent.Response but json.Unmarshal fails. The stored State.Data for done runs must be a valid agent.Response JSON document; corruption or incompatible schema changes break this decode.

Source

Thrown at agent/checkpoint.go:99

	}
	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)
	}
	message := string(run.State.Data)
	parentID := run.ParentID
	a.mu.Lock()
	defer a.mu.Unlock()
	if a.model == nil {
		a.setup()
	}
	return a.askLocked(ctx, run.ID, message, parentID, &run, false)
}

// ResumeInput resumes a checkpointed agent run that paused via the built-in
// request_input tool. The supplied input is appended to the original request so

View on GitHub (pinned to 24529f1404)

Solutions

1. Delete/recreate the checkpoint entry for that run and re-run the agent from scratch, since the stored response is unrecoverable.
2. If upgrading library versions, drain or discard old done checkpoints, or write a migration to transform old Response JSON into the new schema.
3. Verify the checkpoint store round-trips JSON payloads intact (encoding, compression, size limits).
4. Log the underlying %w error from json.Unmarshal to pinpoint the exact schema mismatch.

Example fix

// before
resp, err := agent.Resume(ctx, ag, runID) // old-format stored response
// after
if err != nil && strings.Contains(err.Error(), "response decode") {
    ckpt.Delete(ctx, runID)           // drop incompatible checkpoint
    resp, err = ag.Run(ctx, originalMessage) // re-run
}

run, ok, _ := ckpt.Load(ctx, runID)
if ok && run.Status == "done" {
    var probe agent.Response
    if err := json.Unmarshal(run.State.Data, &probe); err != nil { /* stale/incompatible */ }
}

resp, err := agent.Resume(ctx, ag, runID)
if err != nil && strings.Contains(err.Error(), "response decode") {
    ckpt.Delete(ctx, runID)
    resp, err = ag.Run(ctx, originalMessage)
}

When it happens

Trigger: The checkpoint record's State.Data was written by a different library version whose Response JSON shape is incompatible, the stored bytes were truncated/corrupted, or the store returned non-JSON data for a done run.

Common situations: Upgrading go-micro across a Response struct change while reusing old checkpoints; checkpoint stores that mangle binary/JSON payloads; manually editing or migrating checkpoint rows.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• agent run %s input state decode: %w
• agent: ResumeStreamAsk unsupported by implementation
• agent: ResumeStreamAsk requires a checkpoint
• agent: checkpointed run not found
• agent: checkpointed run is terminal with status

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