gorilla/websocket · error

websocket: internal error, extra used in client mode

Error message

websocket: internal error, extra used in client mode

What it means

This internal sanity-check error is returned by the write path when the caller supplies an extra write buffer while the connection is operating in client mode. In client mode all frames must be masked with a single key, and the library can only apply one mask key to its internal buffer, so any extra bytes would be written unmasked — a protocol violation. It should never occur through normal API use.

Source

Thrown at conn.go:617

		c.writeBuf[framePos+1] = b1 | 127
		binary.BigEndian.PutUint64(c.writeBuf[framePos+2:], uint64(length))
	case length > 125:
		framePos += 6
		c.writeBuf[framePos] = b0
		c.writeBuf[framePos+1] = b1 | 126
		binary.BigEndian.PutUint16(c.writeBuf[framePos+2:], uint16(length))
	default:
		framePos += 8
		c.writeBuf[framePos] = b0
		c.writeBuf[framePos+1] = b1 | byte(length)
	}

	if !c.isServer {
		key := newMaskKey()
		copy(c.writeBuf[maxFrameHeaderSize-4:], key[:])
		maskBytes(key, 0, c.writeBuf[maxFrameHeaderSize:w.pos])
		if len(extra) > 0 {
			return w.endMessage(c.writeFatal(errors.New("websocket: internal error, extra used in client mode")))
		}
	}

	// Write the buffers to the connection with best-effort detection of
	// concurrent writes. See the concurrency section in the package
	// documentation for more info.

	if c.isWriting {
		panic("concurrent write to websocket connection")
	}
	c.isWriting = true

	err := c.write(w.frameType, c.writeDeadline, c.writeBuf[framePos:w.pos], extra)

	if !c.isWriting {
		panic("concurrent write to websocket connection")
	}
	c.isWriting = false

View on GitHub (pinned to e064f32e36)

Solutions

1. Verify you are using the unmodified gorilla/websocket package and not a patched fork
2. If you maintain a fork, audit the NextWriter/write path so extra buffers are only passed for server (unmasked) writes
3. Upgrade to the latest gorilla/websocket version in case this was an internal bug that was fixed

// internal error — log and close
if err := conn.WriteMessage(websocket.TextMessage, data); err != nil {
    if strings.Contains(err.Error(), "internal error") {
        log.Errorf("library internal error: %v", err)
        conn.Close()
    }
}

When it happens

Trigger: An internal code path calls w.write with a non-empty extra buffer on a client-side Conn; effectively unreachable via the public API unless the library internals are patched or a fork misuses NextWriter's buffer machinery.

Common situations: Custom forks or monkey-patched internals of gorilla/websocket; essentially never seen by application developers using the public API.

Related errors

• websocket: internal error, unexpected bytes at end of flate
• websocket: internal error, unexpected text or binary in Read
• websocket: bad handshake
• websocket: invalid compression negotiation
• malformed ws or wss URL

AI-assisted analysis of gorilla/websocket@e064f32e36 (2026-08-31). Data as JSON: /api/errors/bed9222bd3d08517. Report an issue: GitHub.