Repository navigation
docs(failure-modes): document sse read timeouts and fix chunktimeout example - #522
Open
basiliskus wants to merge 4 commits into
Open
basiliskus wants to merge 4 commits into
basiliskus wants to merge 4 commits into
Conversation
…example Section 9 suggested "chunkTimeout": 5000 (5 seconds) and a requestTimeout key that OpenCode does not read. Copied as-is, that would abort nearly every long response with "SSE read timed out". Replace it with the timeouts the usai-provider kit actually sets, explain the SSE read timeout and its automatic retry, and show how to raise chunkTimeout per project.
The quoted "Provider retry (attempt N)" text is Paseo's, not OpenCode's; describe the notice generically. State that chunkTimeout has no default before OpenCode 1.18.27 (the kit's 2 minutes is what introduces the idle timeout) and that `false` disables it. Replace "if retries also fail" with the actual behavior: capped at five since 1.18.17, unbounded before. Link the kit's opencode.jsonc for current values. Refs: #521
basiliskus
marked this pull request as ready for review
October 7, 2026 20:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/KNOWN_FAILURE_MODES.md§9 recommended"chunkTimeout": 5000(5 seconds) and arequestTimeoutkey that OpenCode does not read. Copied as-is, the 5-second value wouldabort nearly every long model response with
SSE read timed out.This replaces the example with the timeouts the
usai-providerkit actually sets(
timeout10 min,chunkTimeout2 min underprovider.usai.options), adds theSSE read timed outretry symptom and its causes (long reasoning,large tool-call generation, or a stall on the proxy/Zscaler/USAi path), notes that
OpenCode retries automatically (capped at five since 1.18.17), that
chunkTimeouthas nodefault before 1.18.27 so the kit's 2 minutes is what introduces the idle timeout, and shows
how to raise or disable it per project.
Related Issues
Fixes #521
Type of Change
Checklist
Test Results
npx --prefix .github/linters markdownlint-cli2 docs/KNOWN_FAILURE_MODES.md): 0 errors.usai-providerkit (agentic-coding-patterns6c6753c, v1.9.0),files/home/usai-config/opencode.jsonc.chunkTimeoutgains its300000 default in
packages/opencode/src/provider/provider.tsat v1.18.27 (absent throughv1.18.26);
RETRY_MAX_RETRIES = 5appears inpackages/opencode/src/session/retry.tsatv1.18.17 (absent at v1.18.16). The
devenv-opencode:1.0.0image used by acq runsOpenCode 1.18.23 (
opencode --versionin a live sandbox), so it has the retry cap but nochunkTimeoutdefault.Provider retry (attempt N): …is Paseo's wording (found in its app bundle), notOpenCode's TUI, hence the generic symptom text.
Additional Notes
Upstream context: anomalyco/opencode#17578 (large tool calls stalling the stream) and
anomalyco/opencode#51879 (open; would stop SSE keep-alive comments from resetting the
timer, which may make these timeouts appear more often).
AI-assisted; reviewed by the author.