Windows 11: restarting serve on the same port fails with ServeError; changing ports works · Issue #55086 · anomalyco/opencode · GitHub
Skip to content

Windows 11: restarting serve on the same port fails with ServeError; changing ports works #55086

Closed as not planned
Closed as not planned
Windows 11: restarting serve on the same port fails with ServeError; changing ports works#55086
Labels
pending closetriaging

Description

@jasincanada
jasincanada
opened on Oct 13, 2026

Summary

On Windows 11 with PowerShell 7, after closing an OpenCode server, launching the server again on the same port fails with Error: Unexpected error followed by ServeError. Switching from port 4100 to 4101 allowed the server to start and the client to connect.

This appears to be a port-release or shutdown-cleanup problem: the previously used port seems to remain unavailable after the server closes. This cause has not been confirmed with socket/process diagnostics.

Environment

  • OS: Windows 11
  • Shell: PowerShell 7
  • OpenCode version: not captured
  • Listening address: 0.0.0.0
  • Failing port: 4100
  • Working replacement port: 4101

Steps to reproduce (reported workflow)

  1. Start opencode serve --hostname 0.0.0.0 --port 4100 --print-logs --log-level INFO.
  2. Close the server. The exact shutdown method was not captured.
  3. Launch the same command again on port 4100.
  4. Observe ServeError.
  5. Change the port to 4101 and launch again. The server starts and the client connects.

Expected behavior

Closing the server should release its listening port so a subsequent server run can reuse it. If binding fails, the error should identify the port and underlying reason rather than only reporting ServeError.

Actual behavior

Repeated launches on port 4100 failed both with and without OPENCODE_SERVER_PASSWORD set. Changing to port 4101 resolved the startup failure.

Representative output (local user paths redacted):

Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
... level=INFO ... message=loading path="<user-config-dir>\config.json"
... level=INFO ... message=loading path="<user-config-dir>\opencode.json"
... level=INFO ... message=loading path="<user-config-dir>\opencode.jsonc"
Error: Unexpected error

ServeError

Workaround

opencode serve --hostname 0.0.0.0 --port 4101 --print-logs --log-level INFO

Update clients to use the replacement port.

Investigation requested

Please investigate whether server shutdown on Windows leaves a listener or child process alive, or otherwise fails to release the port. Please also expose the underlying bind error in the CLI output. No port ownership output was captured, so a lingering process versus another Windows port-binding issue remains unverified.

Activity

  1. opencode-agent commented on Oct 13, 2026

    @opencode-agent
    opencode-agentBot
    on Oct 13, 2026 – with OpenCode Agent
    Contributor

    Thanks for the detailed report, @jasincanada!

    The output you posted (the OPENCODE_SERVER_PASSWORD is not set; server is unsecured warning followed by a bare Error: Unexpected error / ServeError) comes from OpenCode v1 (opencode-ai 0.x/1.x). v1 now only gets fixes for critical bugs such as data loss, security problems or breakage with no workaround. Since changing the port works around this, it's unlikely to be fixed in v1.

    We'd encourage you to try v2 (the @opencode/cli npm package). It's a completely separate implementation, and the v1 code that hid the real bind error behind ServeError doesn't exist there.

    Related issues that may be useful:

    If you see the same problem on v2, or think this is critical, please reply here with the output of opencode --version and netstat -ano | findstr 4100 taken right after the failure.

  2. opencode-agent
    added
    pending close
    triaging
    on Oct 13, 2026

  3. jasincanada commented on Oct 13, 2026

    @jasincanada
    jasincanada
    on Oct 13, 2026
    Author

    Thanks for the reply. Here are the requested diagnostics and a clarification of the shutdown behavior.

    • Windows 11
    • PowerShell 7.6.6
    • opencode --version: 1.18.35
    • Shutdown method: Ctrl+C in the terminal running the server. I had already stopped the port-4100 server this way before collecting the diagnostics below.

    netsh int ipv4 show excludedportrange protocol=tcp did not list any range containing port 4100.

    After that shutdown, netstat -ano | findstr 4100 still showed:

    TCP    127.0.0.1:4100    0.0.0.0:0          LISTENING      64288
TCP    127.0.0.1:4100    127.0.0.1:50591    ESTABLISHED    64288
TCP    127.0.0.1:4100    127.0.0.1:61297    ESTABLISHED    64288
TCP    127.0.0.1:50591   127.0.0.1:4100     ESTABLISHED    25548
TCP    127.0.0.1:61297   127.0.0.1:4100     ESTABLISHED    25548

    Get-CimInstance Win32_Process identified PID 64288 as a still-running opencode.exe from the npm opencode-ai package, with this command line (personal path omitted):

    opencode.exe serve --hostname 127.0.0.1 --port 4100 --print-logs --log-level DEBUG

    Its parent PID 62500 was pwsh.exe (PowerShell 7). PID 25548 was firefox.exe.

    Clarification: the listener captured in these diagnostics was a localhost/DEBUG server instance; the originally reported failed restart attempts used --hostname 0.0.0.0 --log-level INFO.

    These results support a live server process remaining after Ctrl+C, rather than an excluded port or a socket held by a dead PID. They do not establish why Ctrl+C failed to terminate the process, but they narrow the suspected issue to shutdown/interrupt handling in this run. Switching the client-facing server to port 4101 worked.

    I have not tested v2 yet. Is this Ctrl+C shutdown behavior a known v1 issue on Windows, and is there a recommended graceful shutdown method that reliably terminates the server and releases its listener?

  4. opencode-agent commented on Oct 13, 2026

    @opencode-agent
    opencode-agentBot
    on Oct 13, 2026 – with OpenCode Agent
    Contributor

    Thanks for the extra diagnostics, @jasincanada. They show the cause clearly: after Ctrl+C, the opencode.exe serve process (PID 64288) kept running and still held port 4100.

    This is a known v1 problem on Windows. #32932 reports the same thing (v1 serve keeps its port after exit, so the next start fails with ServeError). It was closed as not planned. Since this is v1 (1.18.35) and stopping the leftover process works around it, it's still unlikely to be fixed in v1.

    There's no graceful shutdown that reliably works in v1 on Windows. What should help:

    • End the leftover process. After Ctrl+C, check with netstat -ano | findstr 4100. If the port is still listed as LISTENING, stop the owning PID: Stop-Process -Id <PID> -Force (or taskkill /PID <PID> /F). This frees the port, and you can keep using 4100.
    • Close open browser connections first. Your netstat output shows Firefox with ESTABLISHED connections to the server. Long-lived browser connections, such as an open web UI tab, may keep the server from shutting down. This isn't confirmed, but closing those tabs before Ctrl+C is worth trying.

    If you try v2 (@opencode/cli), note that #53782 reports a similar restart problem after Ctrl+C on Windows, and #50780 says v2's server doesn't handle stop signals. If you see this on v2, a report there or in a new issue, with the same netstat and process details, would help.

  5. jasincanada commented on Oct 14, 2026

    @jasincanada
    jasincanada
    on Oct 14, 2026
    Author

    Is there a graceful way to shutdown the server in either v1 or v2?

  6. opencode-agent commented on Oct 14, 2026

    @opencode-agent
    opencode-agentBot
    on Oct 14, 2026 – with OpenCode Agent
    Contributor

    @jasincanada, there's no maintainer-run Copilot here, so here's what we found in the code:

    v1 (opencode-ai, your 1.18.35): there's no separate shutdown command. Ctrl+C is meant to stop opencode serve, but as you found, on Windows the process can keep running (see #32932, closed as not planned). The reliable way is to check whether the port is still held and end that process:

    netstat -ano | findstr :4100
Stop-Process -Id <PID> -Force   # or: taskkill /PID <PID> /F

    Closing any browser tabs connected to the server before pressing Ctrl+C may also help, but that isn't confirmed.

    v2 (@opencode/cli): by default the server runs as a background service, and you can stop it with a command:

    opencode service status   # is it running, and where
opencode service stop     # stop it and free the port

    opencode service stop asks the server process to exit, waits about 5 seconds, then force-stops it if it's still running, so the port gets freed. To make the service listen like your v1 setup, use opencode service set hostname 0.0.0.0 and opencode service set port 4100. If you start a server in the foreground with opencode serve --port ... instead, Ctrl+C is still the way to stop it. #53782 reports a restart problem after Ctrl+C on Windows in v2.

    If opencode service stop (or Ctrl+C) on v2 also leaves the port held, please open a new issue with your v2 version and the same netstat and process details. As a v1 report, this issue will still be closed.

  7. jasincanada commented on Oct 14, 2026

    @jasincanada
    jasincanada
    on Oct 14, 2026
    Author

    Is linux also impacted by the lack of graceful exit? Does linux also port lock on exit?

  8. opencode-agent commented on Oct 14, 2026

    @opencode-agent
    opencode-agentBot
    on Oct 14, 2026 – with OpenCode Agent
    Contributor

    Mostly no, @jasincanada. On Linux, the kernel closes all of a process's sockets when it exits, so a port can't stay held by a server that has stopped. That part of the Windows behavior (#32932) shouldn't happen there. Node and Bun servers also set SO_REUSEADDR, so a restart on the same port isn't blocked by connections left in TIME_WAIT.

    A port can still be held on Linux if the server process is still running. That's what happened in your case on Windows. On Linux, Ctrl+C sends SIGINT to the foreground process and usually stops opencode serve, and we haven't seen v1 Linux reports of it surviving Ctrl+C. If it ever does, ss -ltnp | grep 4100 shows the owning PID, and kill <PID> (or kill -9 <PID>) frees the port.

    Related v2 reports on Linux:

    This issue will still be closed as a v1 report. If you see this on v2, please open a new issue.

  9. opencode-agent
    closed this as not plannedon Oct 14, 2026

  10. opencode-agent commented on Oct 14, 2026

    @opencode-agent
    opencode-agentBot
    on Oct 14, 2026 – with OpenCode Agent
    Contributor

    Closing as not planned. This is a v1 issue (opencode-ai 1.18.35): on Windows, Ctrl+C can leave the opencode serve process running, so it still holds the port. v1 only gets critical fixes, and there's a workaround: stop the leftover process (Stop-Process -Id <PID> -Force) or use another port. #32932 tracked the same v1 behavior.

    In v2 (@opencode/cli), opencode service stop stops the background server and frees its port. If you see the port stay held on v2, please open a new issue with your v2 version and the netstat/process details, and link #53782 if it's the Ctrl+C case. Thanks for the thorough diagnostics!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    pending closetriaging

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions