--socketmode %q has bits beyond permission bits (keep it wit

Error message

--socketmode %q has bits beyond permission bits (keep it within 0777)

What it means

parseSocketMode rejects --socketmode values that parse as octal but contain bits outside the 0777 permission range (e.g. setuid/setgid/sticky or higher bits). The flag is restricted to plain permission bits.

Source

Thrown at config.go:93

		}
	}
	return out
}

// parseSocketMode parses the --socketmode flag: an octal permission mode
// such as "0700". The empty string means "not set" and leaves the socket
// file to the process umask; an explicit zero is rejected because it would
// make the socket unusable for everyone, owner included.
func parseSocketMode(s string) (os.FileMode, error) {
	if s == "" {
		return 0, nil
	}
	mode, err := strconv.ParseUint(s, 8, 32)
	if err != nil {
		return 0, fmt.Errorf("--socketmode %q is not an octal permission mode (e.g. 0700)", s)
	}
	if mode > 0o777 {
		return 0, fmt.Errorf("--socketmode %q has bits beyond permission bits (keep it within 0777)", s)
	}
	if mode == 0 {
		return 0, fmt.Errorf("--socketmode 0 would make the socket unusable; pick a mode like 0700")
	}
	return os.FileMode(mode), nil
}

// resolveAddresses builds the list of TCP addresses to listen on.
func resolveAddresses(addrlist []string, port int) []string {
	if len(addrlist) > 0 {
		addrs := make([]string, len(addrlist))
		for i, addr := range addrlist {
			addrs[i] = fmt.Sprintf("%s:%d", addr, port)
		}
		return addrs
	}
	return []string{fmt.Sprintf(":%d", port)}
}

View on GitHub (pinned to 7a8683dc7f)

Solutions

Drop extra bits and use a value within 0777, e.g. 0770 for group-writable sockets
Rely on directory permissions or group membership to control socket access instead

Example fix

// before
websocketd --socketmode=4755 --ssl --port=443 ./script.sh
// after
websocketd --socketmode=0755 --ssl --port=443 ./script.sh

Defensive patterns

Strategy: validation

Validate before calling

const mode = parseInt(socketMode, 8);
if (mode > 0o777) throw new Error('socketmode must be within 0777');

Try / catch

if err := parseSocketMode(v); err != nil { log.Warn(err); mode = 0700 }

Prevention

Strip setuid/setgid/sticky bits from any mode you copy (4755 -> 0755)
Remember this flag is a plain permission mask, not a chmod on an executable

When it happens

Trigger: Running websocketd with --socketmode=4755 (setuid bit) or 1777 (sticky bit) or any octal value greater than 0o777.

Common situations: Operators copying modes intended for executables (setuid 4755) onto a Unix socket; trying to set sticky bits expecting they apply to sockets.

Related errors

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