valyala/fasthttp · error

cannot parse somaxconn %q read from %s: %s

Error message

cannot parse somaxconn %q read from %s: %s

What it means

When cfg.Backlog is unset, soMaxConn reads /proc/sys/net/core/somaxconn and parses it as a positive integer to use as the listen backlog. If the file's trimmed contents are not a valid integer or are <= 0, this error reports the raw value and path. The underlying strconv error is included (%s) — it is nil when the value was merely <= 0.

Source

Thrown at tcplisten/tcplisten_linux.go:47

	}
	return nil
}

const fastOpenQlen = 16 * 1024

func soMaxConn() (int, error) {
	data, err := os.ReadFile(soMaxConnFilePath)
	if err != nil {
		// This error may trigger on travis build. Just use SOMAXCONN
		if os.IsNotExist(err) {
			return unix.SOMAXCONN, nil
		}
		return -1, err
	}
	s := strings.TrimSpace(string(data))
	n, err := strconv.Atoi(s)
	if err != nil || n <= 0 {
		return -1, fmt.Errorf("cannot parse somaxconn %q read from %s: %s", s, soMaxConnFilePath, err)
	}

	// Linux stores the backlog in a uint16.
	// Truncate number to avoid wrapping.
	// See https://github.com/golang/go/issues/5030 .
	if n > 1<<16-1 {
		n = maxAckBacklog(n)
	}
	return n, nil
}

func kernelVersion() (int, int) {
	var uname unix.Utsname
	if err := unix.Uname(&uname); err != nil {
		return 0, 0
	}

	rl := uname.Release

View on GitHub (pinned to c96f600972)

Solutions

1. Fix the host value: sysctl -w net.core.somaxconn=<positive int> and persist it in /etc/sysctl.conf
2. Set an explicit Backlog (>0) in tcplisten.Config to bypass the file read entirely
3. Inspect the file: cat /proc/sys/net/core/somaxconn to see the unparseable value
4. Restore the real procfs file if a container image replaced/masked it

Example fix

// before
cfg := tcplisten.Config{} // Backlog 0 -> reads broken somaxconn
ln, err := tcplisten.NewListener(cfg, "tcp", ":8080")
// after
cfg := tcplisten.Config{Backlog: 1024} // avoids /proc read
ln, err := tcplisten.NewListener(cfg, "tcp", ":8080")

func somaxconnOK() bool {
    data, err := os.ReadFile("/proc/sys/net/core/somaxconn")
    if err != nil { return true } // missing file is tolerated by the library
    n, err := strconv.Atoi(strings.TrimSpace(string(data)))
    return err == nil && n > 0
}

ln, err := tcplisten.NewListener(cfg, "tcp", addr)
if err != nil && strings.Contains(err.Error(), "somaxconn") {
    cfg.Backlog = 1024 // fall back to explicit backlog
    ln, err = tcplisten.NewListener(cfg, "tcp", addr)
}

When it happens

Trigger: NewListener with Backlog <= 0 on Linux where /proc/sys/net/core/somaxconn contains non-numeric content or "0"/a negative number.

Common situations: Misconfigured hosts where somaxconn was set to 0; virtualized/modified procfs exposing placeholder content; corrupted or overridden sysctl values; test environments mounting fake procfs files.

Related errors

• cannot determine backlog to pass to listen(2): %w
• cannot enable tcp_fastopen(qlen=%d): %s
• too large hex number
• fasthttp: no cookies found
• fasthttp: invalid cookie value

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