[v2 Windows] opencode2 hangs at "Starting background server..." after reinstall #41746

Activity

1. github-actions

   assigned

   Hona

   on Aug 11, 2026
2. github-actions commented on Aug 11, 2026

   

   github-actionsBot

   on Aug 11, 2026 – with GitHub Actions

   Contributor

   More actions

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

   • opencode2 became stuck starting its managed background server #41696: Similar symptom — opencode2 hangs at "Starting background server..." / stuck starting its managed background server (different root cause suspected: port conflict vs. Windows reinstall, but the failure mode is the same)

   If your issue is distinct from #41696, feel free to add that context to help maintainers differentiate them.
3. opencode-agent

   added

   2.0

   on Aug 11, 2026
4. opencode-agent commented on Aug 11, 2026

   

   opencode-agentBot

   on Aug 11, 2026 – with OpenCode Agent

   Contributor

   More actions

   Thanks for the report. Could you reproduce this once more and share the relevant log output?

   On Windows, the installed-build log is at:

   %USERPROFILE%\.local\share\opencode\log\opencode.log
   

   Please redact API keys, authorization headers, prompts, file contents, and any other sensitive data before sharing it.
5. Double77x commented on Sep 7, 2026

   

   Double77x

   on Sep 7, 2026

   More actions

   Ran into this on Windows. In my case the timeout was caused by a port collision with Windows dynamic port reservations. On Windows, especially with Hyper-V, WSL2 or Docker installed it likes to reserve large blocks of ports.

   The CLI hung and eventually threw:

   • Error: Timed out waiting for the background service to start

   Checking ~/.local/share/opencode/log/opencode.log showed the actual error:

   • Managed service port 49374 on 127.0.0.1 is already in use by another process.

   Running netsh interface ipv4 show excludedportrange protocol=tcp confirmed that Hyper-V/WSL had reserved ports
   49336 to 49435, preventing the background service from binding to 49374.

   Setting an unreserved port resolved it: powershell opencode service set port 40900 opencode service start

   Two improvements would probably help here:

   1. Surface stderr from the background service in the CLI rather than silently waiting for the timeout.
   2. Retry with an alternate port (or request port 0 and persist what the OS assigns) when hitting EADDRINUSE / WSAEACCES.

   👍React with 👍1Reacted by Raymont Qin
6. Double77x

   added a commit that references this issue on Sep 7, 2026

   fix(cli): resolve background service port collision on Windows

   ...

   This issue will close once commit 7487028 is merged into the 'dev' branch.

   7487028
7. humb1t commented on Sep 16, 2026

   

   humb1t

   on Sep 16, 2026

   More actions

   I get same issue on linux machine today
8. laundry-96 commented on Oct 7, 2026

   

   laundry-96

   on Oct 7, 2026

   More actions

   I'm getting the same issue. I have multiple users on my server, so the port can be blocked by other people
9. luzdealba commented on Oct 12, 2026

   

   luzdealba

   on Oct 12, 2026

   More actions

   I had the same issue on WSL after upgrading from v1 to v2 via opencode upgrade --major, even after fully uninstalling and reinstalling via NPM

   In the end, I fully (re)uninstalled and installed via curl -fsSL https://opencode.ai/v2/install | bash — and it worked.

   Seems like the upgrade and NPM or PNPM installations aren't v2-ready yet.

   👍React with 👍2Reacted by Victor Safronov and Dan Leslie
10. opencodejr commented on Oct 28, 2026

    

    opencodejrBot

    on Oct 28, 2026

    More actions

    Thanks for the report, and sorry for the slow reply. 0.0.0-next-17155 is an old pre-release build, and the background service startup on Windows has changed a lot since then. In the comments here, the hang was traced to Windows (Hyper-V / WSL2 / Docker) reserving a range of ports that includes the old default service port 49374. Since v2.2.0, the Windows default port is 28894, outside those ranges, and startup errors are shown instead of a silent hang.

    Could you try the latest v2 release and let us know if it still happens? If it does, please share:

    1. The output of opencode --version.
    2. Any error printed after Starting background server....
    3. The latest entries of %USERPROFILE%\.local\share\opencode\log\opencode.log from that launch. Please remove API keys and other sensitive data first.
    4. The output of netsh interface ipv4 show excludedportrange protocol=tcp.

    If you're stuck on an older version, opencode service set port <port> with a free port below 49152, then opencode service start, has worked around this for others.

    You can reply here with the details, or edit the issue. If you edit it, please also leave a comment saying you've updated it, so we know you're done.

    Related issues, ordered by likelihood that they're the same problem:

    • service: hardcoded default port 49374 with no fallback and a silent hang when it's unavailable #52234: same hang when the default service port can't be bound (WSL2/Hyper-V reserved ranges)
    • [v2 Windows] v2.0.3 times out waiting for background service after local CLI install #49034: Windows, v2.0.3 timing out while waiting for the background service
    • TUI hangs at "Starting background server..." when Desktop app is installed #57978: hang at "Starting background server..." when the Desktop app is also installed
    • opencode2 became stuck starting its managed background server #41696: earlier report of opencode2 stuck starting its background server
    • desktop: background service spawn fails "port in use" on Windows/WSL2 mirrored networking — app stuck at logo, error not logged #55907: Desktop "port in use" on Windows/WSL2 mirrored networking
11. opencodejr

    added

    triaging

    on Oct 28, 2026
12. antigravity-unleashed commented on Oct 28, 2026

    

    antigravity-unleashed

    on Oct 28, 2026 via email

    Author

    More actions

    Thanks for following up! I have upgraded to the latest version and can confirm that the issue is resolved—the background server now starts up properly and everything is working smoothly. Thank you for the fix! You can go ahead and close this issue. 2026年10月29日(木) 6:31 opencodejr[bot] ***@***.***>:

    …

    *opencodejr[bot]* left a comment (anomalyco/opencode#41746) <#41746 (comment)> Thanks for the report, and sorry for the slow reply. 0.0.0-next-17155 is an old pre-release build, and the background service startup on Windows has changed a lot since then. In the comments here, the hang was traced to Windows (Hyper-V / WSL2 / Docker) reserving a range of ports that includes the old default service port 49374. Since v2.2.0, the Windows default port is 28894, outside those ranges, and startup errors are shown instead of a silent hang. Could you try the latest v2 release and let us know if it still happens? If it does, please share: 1. The output of opencode --version. 2. Any error printed after Starting background server.... 3. The latest entries of %USERPROFILE%\.local\share\opencode\log\opencode.log from that launch. Please remove API keys and other sensitive data first. 4. The output of netsh interface ipv4 show excludedportrange protocol=tcp. If you're stuck on an older version, opencode service set port <port> with a free port below 49152, then opencode service start, has worked around this for others. You can reply here with the details, or edit the issue. If you edit it, please also leave a comment saying you've updated it, so we know you're done. Related issues, ordered by likelihood that they're the same problem: - #52234 <#52234>: same hang when the default service port can't be bound (WSL2/Hyper-V reserved ranges) - #49034 <#49034>: Windows, v2.0.3 timing out while waiting for the background service - #57978 <#57978>: hang at "Starting background server..." when the Desktop app is also installed - #41696 <#41696>: earlier report of opencode2 stuck starting its background server - #55907 <#55907>: Desktop "port in use" on Windows/WSL2 mirrored networking — Reply to this email directly, view it on GitHub <#41746?email_source=notifications&email_token=B3VYW7REIMZGNZLD3NHGQCD5WJQULA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMNBYGEYTONJXGY22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-6481175765>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B3VYW7WKIJO364T4UAGWCWL5WJQULAVCNFSNUABFKJSXA33TNF2G64TZHM4TONJXGM2DGMJZHNEXG43VMU5TKMJSGA2TGMRSGI42C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/B3VYW7VMPNSP2FM267N5XG35WJQULA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMNBYGEYTONJXGY22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/B3VYW7QOJZ34LQN5EWFM7YD5WJQULA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMNBYGEYTONJXGY22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>
13. opencodejr

    closed this as not plannedon Oct 31, 2026
14. opencodejr commented on Oct 31, 2026

    

    opencodejrBot

    on Oct 31, 2026

    More actions

    We haven't heard back, so I'm closing this for now. The hang at Starting background server... on 0.0.0-next-17155 was most likely Windows reserving a port range that includes the old default service port 49374. Since v2.2.0, the Windows default port is 28894, outside those ranges, and startup errors are shown instead of a silent hang.

    If it still happens on the latest v2 release, please comment here with the output of opencode --version, any error printed after Starting background server..., and the latest entries from %USERPROFILE%\.local\share\opencode\log\opencode.log (with sensitive data removed). We'll reopen it. In the meantime, opencode service set port <port> with a free port below 49152, followed by opencode service start, works around it. #52234 tracks the same port problem.