valyala/fasthttp · error

prefork: windows only supports reuseport = true

Error message

prefork: windows only supports reuseport = true

What it means

ErrOnlyReuseportOnWindows is returned by fasthttp's prefork package when Prefork is enabled on Windows without setting Reuseport to true. On Windows, prefork relies exclusively on SO_REUSEPORT-style socket sharing; without it, child processes cannot share the listening socket, so the library refuses to start rather than misbehave.

Source

Thrown at prefork/prefork.go:51

	// defaultShutdownGracePeriod is how long the master waits for children to
	// exit cleanly after sending SIGTERM before forcibly killing them.
	defaultShutdownGracePeriod = 5 * time.Second
)

var (
	defaultLogger = Logger(log.New(os.Stderr, "", log.LstdFlags))

	// tcpListenerFile is a hook for (*net.TCPListener).File so tests can
	// inject failure paths without binding a real socket.
	tcpListenerFile = (*net.TCPListener).File

	// ErrOverRecovery is returned when child prefork process restarts exceed
	// the value of RecoverThreshold.
	ErrOverRecovery = errors.New("prefork: exceeding the value of recoverthreshold")

	// ErrOnlyReuseportOnWindows is returned when running on Windows without Reuseport.
	ErrOnlyReuseportOnWindows = errors.New("prefork: windows only supports reuseport = true")

	// ErrCommandProducerNilCmd is returned when a CommandProducer returns
	// (nil, nil) instead of a started command.
	ErrCommandProducerNilCmd = errors.New("prefork: commandproducer returned nil command")

	// ErrCommandProducerNotStarted is returned when a CommandProducer returns
	// an *exec.Cmd whose Process is nil (i.e. cmd.Start() was not called).
	ErrCommandProducerNotStarted = errors.New("prefork: commandproducer must return a started command")
)

// Logger is used for logging formatted messages. Its method set is intentionally
// identical to fasthttp.Logger so that *fasthttp.Server.Logger can be assigned
// directly.
type Logger interface {
	// Printf must have the same semantics as log.Printf.
	Printf(format string, args ...any)
}

View on GitHub (pinned to c96f600972)

Solutions

1. Set Reuseport: true on the preforker before starting on Windows.
2. Alternatively, disable prefork on Windows (enable it only on Linux/BSD builds).
3. Run the preforked service on a Linux/Unix host where Reuseport is not mandatory.

Example fix

// before
pf := &prefork.Prefork{RecoverThreshold: 3}
// after
pf := &prefork.Prefork{RecoverThreshold: 3, Reuseport: true} // required on Windows

if runtime.GOOS == "windows" && !pf.Reuseport {
    pf.Reuseport = true // prefork on Windows requires Reuseport
}

When it happens

Trigger: Calling prefork (e.g. prefork.Start or app startup with Prefork enabled) on a Windows host while preforker.Reuseport is false (the default).

Common situations: Developers enabling prefork on Windows dev machines or Windows Server deployments after copying Linux-oriented prefork config; forgetting that Reuseport must be explicitly opted into on Windows.

Related errors

• fasthttp: connection pool strategy is not implement
• proxy: unknown scheme:
• fasthttp: no available clients
• prefork: exceeding the value of recoverthreshold
• prefork: commandproducer returned nil command

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/dd2b34e17bcefb81. Report an issue: GitHub.