Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix tools.read: out-of-range offset should not abort runs (clamp or return diagnostic) [3 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#52680•Fetched 2026-04-08 01:20:28
View on GitHub
Comments
1
Participants
2
Timeline
13
Reactions
0
Author
LyHugLyHug
Participants
Hollychou924Hollychou924LyHugLyHug
Timeline (top)
referenced ×9cross-referenced ×3commented ×1

The tools.read tool can hard-fail a run when the requested offset is beyond end-of-file. This is easy for models/agents to hit when the file length changes or when they guess offsets.

Today this failure aborts the entire job/run, even though it should be a recoverable/diagnostic situation.

Error Message

  • Or return an empty result + explicit diagnostic error object, but do not throw.

Root Cause

Observed

  • Some runs fail with errors like:
    • Read: lines 200-319 from ... pending-actions.yaml failed
    • Root cause: offset requested is past EOF, and the read tool throws.

Fix Action

Fix / Workaround

In locate-1, read-offset beyond EOF contributed to run failures. After applying a local clamp workaround, the soak test reached 10/10 ok in locate-4.

PR fix notes

PR #52726: read: recover from out-of-range offsets

Description (problem / solution / changelog)

Summary

  • Problem: read aborts the whole run when the requested offset is past EOF.
  • Why it matters: models regularly guess stale offsets after file changes, so this turns a recoverable paging mistake into a fatal tool failure.
  • What changed: the OpenClaw read wrapper now catches the upstream out-of-range offset error, recovers to a valid offset, and returns a diagnostic note plus content instead of throwing.
  • What did NOT change (scope boundary): this does not patch @mariozechner/pi-coding-agent itself or change normal in-range read behavior.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Closes #52680
  • Related #49501

User-visible / Behavior Changes

  • read no longer aborts a run when offset is beyond EOF.
  • Out-of-range reads now return a diagnostic note and recover to a valid offset.
  • Limited reads recover to the last valid window instead of throwing.

Security Impact (required)

  • New permissions/capabilities? (Yes/No) No
  • Secrets/tokens handling changed? (Yes/No) No
  • New/changed network calls? (Yes/No) No
  • Command/tool execution surface changed? (Yes/No) No
  • Data access scope changed? (Yes/No) No
  • If any Yes, explain risk + mitigation:

Repro + Verification

Environment

  • OS: Windows 11
  • Runtime/container: Node via pnpm test
  • Model/provider: N/A
  • Integration/channel (if any): agent read tool wrapper
  • Relevant config (redacted): default local test config

Steps

  1. Create a file with a few lines.
  2. Call read with offset larger than the file length.
  3. Observe the current tool error aborting the run.

Expected

  • The run should continue.
  • The tool should return a diagnostic and a valid recovery result.

Actual

  • Before this patch, the upstream read tool throws Offset ... is beyond end of file (...).

Evidence

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

  • Verified scenarios: targeted Vitest coverage for out-of-range recovery and workspace-root guard behavior; manual tsx repro showing non-fatal recovery text for offset=200 on a 4-line file.
  • Edge cases checked: explicit limit now recovers to the last valid tail window instead of falling back to line 1.
  • What you did not verify: full repo pnpm test; a broad existing test file currently fails locally due a missing @modelcontextprotocol/sdk import chain unrelated to this change.

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? (Yes/No) Yes
  • Config/env changes? (Yes/No) No
  • Migration needed? (Yes/No) No
  • If yes, exact upgrade steps:

Failure Recovery (if this breaks)

  • How to disable/revert this change quickly: revert commit Read: recover from out-of-range offsets.
  • Files/config to restore: src/agents/pi-tools.read.ts
  • Known bad symptoms reviewers should watch for: unexpected read diagnostic notes on in-range offsets.

Risks and Mitigations

  • Risk: recovery window could return an unexpected chunk if upstream read paging defaults change again.
  • Mitigation: the wrapper only uses recovery for the specific upstream EOF-offset error and adds focused regression coverage for both unlimited and limited reads.

Changed files

  • src/agents/pi-tools.read.offset-recovery.test.ts (added, +115/-0)
  • src/agents/pi-tools.read.ts (modified, +140/-3)

PR #52739: fix(agents): clamp out-of-range read offset instead of aborting run

Description (problem / solution / changelog)

Summary

When tools.read receives an offset beyond the file's total lines, the entire agent run aborts with an uncaught exception. This PR catches the error and falls back to reading from line 1 with a diagnostic note, allowing the agent to continue.

Changes

  • src/agents/pi-tools.read.ts: Wrap base.execute in executeReadWithAdaptivePaging with a try-catch that detects offset/range errors, retries from line 1, and returns a diagnostic result (ok=true) instead of throwing.
  • src/agents/pi-tools.read.offset-clamp.test.ts (new): Unit tests covering offset-beyond-EOF scenarios — verifies diagnostic text is returned, ok=true, and fallback to line 1.

Behavior

BeforeAfter
offset > totalLines → throws → run abortsoffset > totalLines → catches → retries from line 1 → returns result with diagnostic note

Closes #52680

Changed files

  • src/agents/pi-tools.read.offset-clamp.test.ts (added, +281/-0)
  • src/agents/pi-tools.read.ts (modified, +96/-3)

PR #54121: read: recover from out-of-range offsets

Description (problem / solution / changelog)

Supersedes #52726.

What changed

  • replay the original offset recovery patch onto current main
  • document the upstream error-message coupling for the recovery regex
  • change the recovery notice to say "Returning up to..." and update the focused test expectations

Validation

  • pnpm exec vitest run src/agents/pi-tools.read.offset-recovery.test.ts

Changed files

  • src/agents/pi-tools.read.offset-recovery.test.ts (added, +219/-0)
  • src/agents/pi-tools.read.ts (modified, +189/-5)
RAW_BUFFERClick to expand / collapse

Summary

The tools.read tool can hard-fail a run when the requested offset is beyond end-of-file. This is easy for models/agents to hit when the file length changes or when they guess offsets.

Today this failure aborts the entire job/run, even though it should be a recoverable/diagnostic situation.

Environment

  • OpenClaw: 2026.3.13 (cli banner shows commit 61d171a)
  • OS: Linux
  • Node: v25.8.1

Observed

  • Some runs fail with errors like:
    • Read: lines 200-319 from ... pending-actions.yaml failed
    • Root cause: offset requested is past EOF, and the read tool throws.

Expected

  • tools.read should never abort the whole run just because offset is out-of-range.

Preferable behavior:

  • Clamp the offset to the valid range (e.g. to the last page or line 1) and return a diagnostic note.
  • Or return an empty result + explicit diagnostic error object, but do not throw.

Repro (deterministic)

  1. Pick a file with ~100 lines.
  2. Call tools.read with offset=200.
  3. The tool fails/throws and the run aborts.

Evidence

Soak-test summary + logs from a downstream integration repo:

  • docs/test-artifacts/openclaw/2026-03-23-stability-locate-1/summary.json
  • docs/test-artifacts/openclaw/2026-03-23-stability-locate-4/summary.json

In locate-1, read-offset beyond EOF contributed to run failures. After applying a local clamp workaround, the soak test reached 10/10 ok in locate-4.

Suggested fix

In the read tool implementation:

  • If offset >= totalLines (or equivalent), clamp to a safe value and include a short diagnostic warning in the output.
  • Ensure the tool returns ok=true in this case so agent logic can proceed.

extent analysis

Fix Plan

To fix the issue, we need to modify the tools.read implementation to clamp the offset to a valid range and return a diagnostic note instead of throwing an error.

Step-by-Step Solution

  • Check if the requested offset is beyond the end-of-file
  • If it is, clamp the offset to the last valid line or line 1
  • Return a diagnostic note along with the clamped result
  • Ensure the tool returns ok=true in this case

Example Code

// tools.read implementation
function read(offset, totalLines) {
  if (offset >= totalLines) {
    // Clamp offset to last valid line
    offset = totalLines - 1;
    // Return diagnostic note
    return {
      ok: true,
      result: [],
      diagnostic: `Offset ${offset} is out of range, clamped to ${totalLines - 1}`
    };
  }
  // Rest of the implementation remains the same
}

Verification

To verify the fix, you can test the tools.read function with an offset beyond the end-of-file and check if it returns a diagnostic note with ok=true.

Extra Tips

  • Make sure to handle edge cases, such as an empty file or an offset of 0.
  • Consider adding logging or monitoring to track instances where the offset is clamped, to help identify potential issues with the models or agents.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#permission error#memory optimization#batch processing#GPU compatibility#latency issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING