siyuan-note/siyuan · error

invalid agent runtime revision

Error message

invalid agent runtime revision

What it means

loadRuntimeLocked validates the persisted Revision counter and rejects negative values. The revision is a monotonically increasing version used for optimistic concurrency (compared against turn.BaseRevision elsewhere), so a negative revision is structurally meaningless and indicates a corrupted or hand-edited runtime file.

Solutions

1. Inspect the runtime JSON and restore revision to a correct non-negative value from a backup
2. If no backup exists, delete the runtime state for that session so the kernel rebuilds it
3. Avoid editing session runtime files directly; always mutate them through the kernel APIs that bump the revision

Example fix

// before (runtime JSON)
"revision": -3
// after
"revision": 3

const runtime = JSON.parse(readRuntimeFile(sessionDir));
if (typeof runtime.revision !== "number" || runtime.revision < 0) throw new Error("runtime revision corrupt");

When it happens

Trigger: Loading any session whose runtime JSON contains "revision": -N; hand-editing sessions/<id>/ runtime file; a partial/failed write that left a sentinel or garbage value in the field.

Common situations: Manual editing of the runtime JSON; an external tool rewriting session state; disk corruption in the workspace data directory.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• agent session revision conflict
• capability was not exposed in this model round
• frontend capability description is required
• image MIME type is missing
• invalid agent runtime turn

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/8d8909136b3e3b7d. Report an issue: GitHub.

Appendix: source

Thrown at kernel/agent/runtime.go:210

	data, err := os.ReadFile(runtimePath(sessionID))
	if err != nil {
		if os.IsNotExist(err) {
			return &agentRuntime{SchemaVersion: 1, SessionID: sessionID}, nil
		}
		return nil, err
	}
	var runtime agentRuntime
	if err := gulu.JSON.UnmarshalJSON(data, &runtime); err != nil {
		return nil, err
	}
	if runtime.SchemaVersion > 1 {
		return nil, fmt.Errorf("unsupported agent runtime schema version: %d", runtime.SchemaVersion)
	}
	if runtime.SessionID != "" && runtime.SessionID != sessionID {
		return nil, fmt.Errorf("agent runtime session id mismatch")
	}
	if runtime.Revision < 0 {
		return nil, fmt.Errorf("invalid agent runtime revision")
	}
	if runtime.ActiveTurn != nil {
		if runtime.ActiveTurn.TurnID == "" {
			return nil, fmt.Errorf("invalid agent runtime turn id")
		}
		switch runtime.ActiveTurn.State {
		case "running", "finished", "interrupted":
		default:
			return nil, fmt.Errorf("invalid agent runtime turn state")
		}
	}
	if runtime.SchemaVersion == 0 {
		runtime.SchemaVersion = 1
	}
	if runtime.SessionID == "" {
		runtime.SessionID = sessionID
	}
	return &runtime, nil

View on GitHub (pinned to 9f775e8a12)