Fix WebSocketError: websocket: close 1006 (abnormal closure): unexpected EOF in Echo

This error occurs when a WebSocket connection closes unexpectedly without a proper close handshake, typically because the client disconnected, a proxy timed out, or the server did not handle read errors gracefully. Fix it by implementing proper close handling, setting read deadlines with pong handlers, and distinguishing normal disconnects from real errors.

Reading the Stack Trace

Here's what each line means:

• main.handleWS({0x1029e4f80, 0x14000226000}) /app/handlers/ws.go:25 +0x2d8: The WebSocket handler at line 25 encounters an abnormal closure when the client disconnects without sending a close frame.
• github.com/gorilla/websocket.(*Conn).ReadMessage(0x14000196040): ReadMessage returns an error because the connection was closed unexpectedly by the remote peer.
• github.com/gorilla/websocket.(*Conn).NextReader(0x14000196040): NextReader detects the broken connection and returns an unexpected EOF error.

Common Causes

func handleWS(c echo.Context) error {
	conn, _ := upgrader.Upgrade(c.Response(), c.Request(), nil)
	defer conn.Close()
	for {
		_, msg, err := conn.ReadMessage()
		if err != nil {
			log.Println("error:", err) // logs every normal disconnect as error
			break
		}
		conn.WriteMessage(websocket.TextMessage, msg)
	}
	return nil
}

_, msg, err := conn.ReadMessage()
if err != nil {
	log.Printf("WEBSOCKET ERROR: %v", err) // includes normal closes
	break
}

func broadcast(clients map[*websocket.Conn]bool, msg []byte) {
	for conn := range clients {
		conn.WriteMessage(websocket.TextMessage, msg) // may be closed
	}
}

The Fix

Implement ping/pong keepalive to detect dead connections proactively. Set read deadlines that reset on pong receipt. Use IsUnexpectedCloseError to filter normal disconnects from actual errors, reducing log noise.

func handleWS(c echo.Context) error {
	conn, _ := upgrader.Upgrade(c.Response(), c.Request(), nil)
	defer conn.Close()
	for {
		_, msg, err := conn.ReadMessage()
		if err != nil {
			log.Println("error:", err)
			break
		}
		conn.WriteMessage(websocket.TextMessage, msg)
	}
	return nil
}

const (
	pongWait   = 60 * time.Second
	pingPeriod = (pongWait * 9) / 10
)

func handleWS(c echo.Context) error {
	conn, err := upgrader.Upgrade(c.Response(), c.Request(), nil)
	if err != nil {
		return echo.NewHTTPError(http.StatusBadRequest, "websocket upgrade failed")
	}
	defer conn.Close()

	conn.SetReadDeadline(time.Now().Add(pongWait))
	conn.SetPongHandler(func(string) error {
		conn.SetReadDeadline(time.Now().Add(pongWait))
		return nil
	})

	// Ping ticker
	ticker := time.NewTicker(pingPeriod)
	defer ticker.Stop()

	go func() {
		for range ticker.C {
			if err := conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(10*time.Second)); err != nil {
				return
			}
		}
	}()

	for {
		msgType, msg, err := conn.ReadMessage()
		if err != nil {
			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
				log.Printf("unexpected ws close: %v", err)
			}
			break
		}
		if err := conn.WriteMessage(msgType, msg); err != nil {
			break
		}
	}
	return nil
}

Testing the Fix

package handlers_test

import (
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"

	"github.com/gorilla/websocket"
	"github.com/labstack/echo/v4"
	"github.com/stretchr/testify/assert"
)

func TestWebSocket_EchoMessage(t *testing.T) {
	e := echo.New()
	e.GET("/ws", handleWS)
	s := httptest.NewServer(e)
	defer s.Close()

	url := "ws" + strings.TrimPrefix(s.URL, "http") + "/ws"
	conn, _, err := websocket.DefaultDialer.Dial(url, nil)
	assert.NoError(t, err)
	defer conn.Close()

	conn.WriteMessage(websocket.TextMessage, []byte("hello"))
	_, msg, err := conn.ReadMessage()
	assert.NoError(t, err)
	assert.Equal(t, "hello", string(msg))
}

func TestWebSocket_CleanClose(t *testing.T) {
	e := echo.New()
	e.GET("/ws", handleWS)
	s := httptest.NewServer(e)
	defer s.Close()

	url := "ws" + strings.TrimPrefix(s.URL, "http") + "/ws"
	conn, _, err := websocket.DefaultDialer.Dial(url, nil)
	assert.NoError(t, err)

	err = conn.WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""))
	assert.NoError(t, err)
}

Run your tests:

go test ./handlers/... -v

Pushing Through CI/CD

git checkout -b fix/echo-websocket-error,git add handlers/ws.go handlers/ws_test.go,git commit -m "fix: add ping/pong keepalive and graceful close handling for WebSocket",git push origin fix/echo-websocket-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm WebSocket lifecycle works.
2. Open a pull request with the keepalive changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify WebSocket stability in staging.

Frequently Asked Questions