joewalnes/websocketd · error

too many forks active

Error message

too many forks active

What it means

ErrForkNotAllowed is returned by WebsocketdServer.noteForkCreated when the number of concurrently running child processes has reached the configured fork limit (--maxforks). It prevents the server from spawning more processes than allowed.

Source

Thrown at libwebsocketd/http.go:26

import (
	"errors"
	"fmt"
	"html"
	"net"
	"net/http"
	"net/http/cgi"
	"net/textproto"
	"net/url"
	"os"
	"path"
	"path/filepath"
	"regexp"
	"strings"

	"github.com/gorilla/websocket"
)

var ErrForkNotAllowed = errors.New("too many forks active")

var upgradeRe = regexp.MustCompile(`(?i)(^|[,\s])Upgrade($|[,\s])`)

// WebsocketdServer presents http.Handler interface for requests libwebsocketd is handling.
type WebsocketdServer struct {
	Config   *Config
	Log      *LogScope
	forks    chan byte
	hostname string // cached os.Hostname(), computed once at startup
}

// NewWebsocketdServer creates WebsocketdServer struct with pre-determined config, logscope and maxforks limit
func NewWebsocketdServer(config *Config, log *LogScope, maxforks int) *WebsocketdServer {
	hostname, err := os.Hostname()
	if err != nil {
		hostname = "UNKNOWN"
	}
	mux := &WebsocketdServer{

View on GitHub (pinned to 7a8683dc7f)

Solutions

1. Raise the fork limit with --maxforks (or set it appropriately for expected concurrency)
2. Investigate child processes that hang and never release their fork slot
3. Add client-side backoff/retry with delay instead of immediate reconnect loops
4. Scale horizontally: run more websocketd instances behind a load balancer

Example fix

// before
websocketd --port=8080 --maxforks=2 ./worker.sh
// after
websocketd --port=8080 --maxforks=100 ./worker.sh

// check your client's expected concurrency vs --maxforks before deploying
// e.g. maxConcurrentClients must be <= --maxforks

// reconnect with exponential backoff on close
ws.onclose = () => setTimeout(connect, Math.min(30000, 1000 * 2 ** attempt++));

When it happens

Trigger: noteForkCreated (libwebsocketd/http.go:331) is called in the default branch of its internal counter check once the active-fork counter is at the maximum; each new client connection that would spawn a process while the limit is hit gets this error.

Common situations: Too many simultaneous WebSocket clients for the configured --maxforks value; leaked/hung child scripts that never exit consume fork slots; load spikes from reconnecting clients.

Related errors

• script not found
• --maxframesize must not be negative; use 0 for unlimited
• same origin policy violated
• origin list matches were not found
• 500 Internal Server Error

AI-assisted analysis of joewalnes/websocketd@7a8683dc7f (2026-09-03). Data as JSON: /api/errors/d4eccd108078a553. Report an issue: GitHub.