Skip to content

fix: improve context overflow error messages and docs#18997

Closed
realhoratiobot wants to merge 1 commit intoopenclaw:mainfrom
realhoratiobot:fix/context-overflow-ux-5771
Closed

fix: improve context overflow error messages and docs#18997
realhoratiobot wants to merge 1 commit intoopenclaw:mainfrom
realhoratiobot:fix/context-overflow-ux-5771

Conversation

@realhoratiobot
Copy link

@realhoratiobot realhoratiobot commented Feb 17, 2026

Summary

Improves the user experience when hitting context overflow errors (#5771).

Changes

Error messages (src)

  • Include context window size, source, and message count in the overflow error so users can diagnose the issue
  • Add actionable suggestions: reduce workspace files, lower bootstrapMaxChars, use /reset
  • Improve diagnostic logging with contextWindow and contextSource fields

Documentation (docs)

  • Document agents.defaults.compaction config with full example (mode, reserveTokensFloor, memoryFlush)
  • Document related settings: contextTokens, bootstrapMaxChars, bootstrapTotalMaxChars
  • Clarify that autoCompact is NOT a config key (common user confusion from the issue)
  • Add troubleshooting section for context overflow

Before

Context overflow: prompt too large for the model. Try again with less input or a larger-context model.

After

Context overflow: prompt too large for the model. Context window: 200,000 tokens (source: default). Messages in session: 3. Try /reset (or /new) to start a fresh session, reduce workspace files (AGENTS.md, SOUL.md, etc.), lower `agents.defaults.bootstrapMaxChars`, or switch to a larger-context model.

Testing

  • pnpm build passes
  • Existing unit tests pass (run.overflow-compaction.test.ts, config.compaction-settings.test.ts)
  • AI-assisted (Claude via OpenClaw)

Closes #5771

Greptile Summary

Improves context overflow error messages with actionable diagnostic information (context window size, source, message count) and adds comprehensive compaction documentation including config examples, related settings, and a troubleshooting section.

  • run.ts: Error message now includes dynamic context info (window size, source, message count) and specific remediation steps
  • agent-runner-execution.ts: Catch-all fallback message updated with consistent suggestions (/reset, reduce workspace files, switch model)
  • compaction.md: Added YAML config example, related settings table, autoCompact clarification, and troubleshooting section — all verified against source code
  • Issue found: The e2e test in reply.triggers.trigger-handling.ignores-inline-elevated-directive-unapproved-sender.e2e.test.ts (line 140-142) uses toBe() exact match against the old fallback message from agent-runner-execution.ts and was not updated in this PR — this test will fail

Confidence Score: 3/5

  • Low-risk changes to error messages and docs, but an existing e2e test will break due to an exact string match on the old message.
  • The code changes are straightforward improvements to error messages and logging, and the documentation additions are accurate. However, the e2e test reply.triggers.trigger-handling.ignores-inline-elevated-directive-unapproved-sender.e2e.test.ts expects the old message string via toBe() and was not updated, which will cause a test failure. Score of 3 reflects that the functional changes are sound but the PR is not merge-ready until the test is fixed.
  • Pay close attention to src/auto-reply/reply/agent-runner-execution.ts — the updated error message at line 544 breaks an e2e test that was not included in this PR's changes.

Last reviewed commit: 1eef057

(2/5) Greptile learns from your feedback when you react with thumbs up/down!

- Include context window size, source, and message count in overflow error
- Add actionable suggestions: reduce workspace files, lower bootstrapMaxChars
- Document compaction config keys with examples in docs
- Add troubleshooting section for context overflow
- Clarify that autoCompact is not a config key (common user confusion)
- Improve diagnostic logging with contextWindow and contextSource fields

Closes openclaw#5771
@openclaw-barnacle openclaw-barnacle bot added docs Improvements or additions to documentation agents Agent runtime and tooling size: XS labels Feb 17, 2026
@alaindimabuyo
Copy link

@greptileai please review

Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 files reviewed, 1 comment

Edit Code Review Agent Settings | Greptile

Comment on lines 543 to +544
const fallbackText = isContextOverflow
? "⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."
? "⚠️ Context overflow — prompt too large for this model. Try /reset or /new for a fresh session, reduce workspace files, or switch to a larger-context model."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

E2e test expects the old message string

The test in reply.triggers.trigger-handling.ignores-inline-elevated-directive-unapproved-sender.e2e.test.ts (line 140-142) uses toBe() (exact match) against the previous message:

"⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."

But this line now returns:

"⚠️ Context overflow — prompt too large for this model. Try /reset or /new for a fresh session, reduce workspace files, or switch to a larger-context model."

That test needs to be updated to match the new message, otherwise it will fail.

Prompt To Fix With AI
This is a comment left during a code review.
Path: src/auto-reply/reply/agent-runner-execution.ts
Line: 543:544

Comment:
**E2e test expects the old message string**

The test in `reply.triggers.trigger-handling.ignores-inline-elevated-directive-unapproved-sender.e2e.test.ts` (line 140-142) uses `toBe()` (exact match) against the previous message:

```
"⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."
```

But this line now returns:

```
"⚠️ Context overflow — prompt too large for this model. Try /reset or /new for a fresh session, reduce workspace files, or switch to a larger-context model."
```

That test needs to be updated to match the new message, otherwise it will fail.

How can I resolve this? If you propose a fix, please make it concise.

@steipete
Copy link
Contributor

Closing as AI-assisted stale-fix triage.

Linked issue #5771 ("[Bug]: Context overflow error") is CLOSED and was closed on 2026-02-23T16:33:28Z with state reason COMPLETED.
Given that issue status, this fix PR is no longer needed in the active queue and is being closed as stale.

If the behavior is still reproducible on current main, reopen #18997 (or open a new focused fix PR) and reference #5771.

@steipete steipete closed this Feb 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation size: XS

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Context overflow error

3 participants