OpenCode hangs/freezes mid-stream on Starlink satellite internet connection

[gabrielbuzziv]

Description

OpenCode consistently hangs during tool execution (Read, Glob, Grep) when using Starlink satellite internet. The same setup works perfectly when switching to 4G mobile connection.

The issue appears to be related to Starlink's network characteristics (satellite handoffs, latency jitter, CGNAT) causing the streaming HTTP connection to drop or stall without proper error handling/recovery.

Environment

• OpenCode version: 1.1.14
• OS: Ubuntu 22.04
• Node version: 22 (also tested with 24)
• Internet: Starlink satellite
• Provider: OpenCode Zen (also tested with OpenRouter - same issue)
• Terminal: Default

Steps to reproduce

1. Connect to Starlink internet
2. Open a Next.js project with App Router structure
3. Ask OpenCode to analyze or fix code that requires reading multiple files
4. OpenCode starts executing tools (Read, Glob, Grep)
5. Mid-execution, it freezes with spinner showing "Reading file..." or similar
6. No error message is displayed
7. Logs show streaming started but then stops receiving message.part.updated events

Expected behavior

Tool execution completes and assistant responds, even on high-latency/unstable connections.

Actual behavior

OpenCode hangs indefinitely. The last log entries show:
```
INFO service=llm providerID=opencode modelID=claude-sonnet-4-5 ... stream
INFO service=bus type=message.part.updated publishing
INFO service=bus type=message.part.updated publishing
... (stream stops, no more entries)
```

Workaround

Switching from Starlink to 4G mobile connection resolves the issue completely.

Additional context

Starlink network characteristics that may cause this:

• Frequent satellite handoffs causing brief connection interruptions
• High latency jitter (20ms to 200ms+)
• Aggressive CGNAT with shorter connection timeouts
• TCP connections may be silently reset during satellite switches

Diagnostics performed:

• ✅ curl to api.opencode.ai works (both IPv4 and IPv6)
• ✅ No proxy configured
• ✅ DNS resolution works
• ✅ inotify limits are sufficient (65k+)
• ✅ Node 22 LTS installed
• ✅ Glob/filesystem operations work outside OpenCode
• ❌ NODE_OPTIONS="--dns-result-order=ipv4first" did not help

Possibly related issues:

• lsp bug: edit tool stalls after first diff; assistant hangs #6959 - LSP bug: edit tool stalls after first diff; assistant hangs
• Opencode Hangs when used as CLI tool #5888 - OpenCode Hangs when used as CLI tool

Suggested improvements

1. Implement connection retry/reconnect logic for streaming responses
2. Add configurable timeout settings for unstable connections
3. Better error handling when stream drops - show error instead of hanging
4. Optional non-streaming fallback mode for problematic networks

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• lsp bug: edit tool stalls after first diff; assistant hangs #6959: lsp bug: edit tool stalls after first diff; assistant hangs - Similar symptoms of streaming hanging/stalling mid-operation
• Opencode Hangs when used as CLI tool #5888: Opencode Hangs when used as CLI tool - Reports hanging during tool execution, possibly related to request failures and stream handling
• [Critical] CLI hangs on second run (Deadlock) on Linux ARM64 (Proot/Container environments) #7843: [Critical] CLI hangs on second run (Deadlock) on Linux ARM64 - Hangs/deadlock issues on certain environments
• Permission check for tool-output directory never matches, causes hang in headless mode #7876: Permission check for tool-output directory never matches, causes hang in headless mode - Hang in headless mode without proper error handling
• High Virtual Memory usage causing system to hang and also made other applications pause/hang. #7752: High Virtual Memory usage causing system to hang - System-level hangs during long-running operations
• Syntax error in opencode.json will cause opencode startup to hang indefinitely #7789: Syntax error in opencode.json will cause opencode startup to hang indefinitely - Hangs without error display

Feel free to ignore if none of these address your specific case.

[goniz]

This one is interesting 😆
I bet it's MTU, it's always MTU's fault ⛏️

[andrea-nurale]

I have the same issue

[tim-sh]

Hi @gabrielbuzziv,

I observed this issue with SAP AI Core (anthropic--claude-4.5-opus) on WiFi.

Evidence from strace investigation

Using strace on opencode v1.1.59, I captured a session where the LLM stream appeared to hang for over 2 hours:

Time	Event
13:37:47	session.prompt step=36 started
13:37:48	service=llm providerID=sap-ai-core modelID=anthropic--claude-4.5-opus ... stream
13:37:48 – 15:40:02	No log entries
15:40:02	session.prompt cancel (manual abort via UI)

Observations:

• No StreamIdleTimeoutError was logged during this period
• Health checks continued responding throughout (~10s intervals)
• The hang occurred after a merge conflict during a git stash operation

Strace-level detail

The process was blocked on epoll_wait() as expected for async I/O, and health check requests were processed normally during this time. This indicates the event loop was running – the hang was specific to the LLM streaming call not receiving any data, rather than a process-wide freeze.

Cheers,
Tim