caddyserver/caddy · error

owner of the socket requires '-w-' (write, octal: '2') permi

Error message

owner of the socket requires '-w-' (write, octal: '2') permissions at least; got '%s' in %s

What it means

After parsing octal permission bits for a unix socket, Caddy requires the owner (first digit triad) to include the write bit. FileMode.String() is inspected and the owner triad must contain 'w'. Modes like 0422 or 002 (read/execute only for the owner) are rejected because the socket owner must be able to write.

Source

Thrown at internal/sockets.go:47

// Permission bits will default to 0200 if none are specified.
// Throws an error, if the first carrying bit does not
// include write perms (e.g. `0422` or `022`).
// Symbolic permission representation (e.g. `u=w,g=w,o=w`)
// is not supported and will throw an error for now!
func SplitUnixSocketPermissionsBits(addr string) (path string, fileMode fs.FileMode, err error) {
	addrSplit := strings.SplitN(addr, "|", 2)

	if len(addrSplit) == 2 {
		// parse octal permission bit string as uint32
		fileModeUInt64, err := strconv.ParseUint(addrSplit[1], 8, 32)
		if err != nil {
			return "", 0, fmt.Errorf("could not parse octal permission bits in %s: %v", addr, err)
		}
		fileMode = fs.FileMode(fileModeUInt64)

		// FileMode.String() returns a string like `-rwxr-xr--` for `u=rwx,g=rx,o=r` (`0754`)
		if string(fileMode.String()[2]) != "w" {
			return "", 0, fmt.Errorf("owner of the socket requires '-w-' (write, octal: '2') permissions at least; got '%s' in %s", fileMode.String()[1:4], addr)
		}

		return addrSplit[0], fileMode, nil
	}

	// default to 0200 (symbolic: `u=w,g=,o=`)
	// if no permission bits are specified
	return addr, 0o200, nil
}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Ensure the owner digit includes write: use 0620, 0600, 0660, 0666, or at minimum 0200.
2. Drop the permission suffix to get the safe default of 0200 (owner write only).
3. If sharing the socket with a client process, add group bits rather than removing owner write: 'path|0620'.

Example fix

// before
unix/run/caddy.sock|0422
// after: owner write bit set, group read
unix/run/caddy.sock|0620

func ownerCanWrite(mode uint32) bool {
    return mode&0o200 != 0
}

// use before building the address:
// if !ownerCanWrite(mode) { /* fix mode */ }

When it happens

Trigger: Listening on 'unix/path/to/socket|0422' or 'unix/path|0400' — any mode whose owner octal digit lacks the 2 bit (0, 1, 4, 5). Even group/other write bits (e.g. 0042) do not satisfy the requirement; the check is strictly on the owner triad at String()[2].

Common situations: Users copy a full chmod-style mode such as 0422 (intended for files where group/other write matters) into the socket address. Or they compute a mode where the owner only gets read (0400) thinking the server only reads the socket.

Related errors

• could not parse octal permission bits in %s: %v
• unable to set permissions (%s) on %s: %v
• invalid action type
• no identifiers configured
• parsing listener address: %v

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/d91dce138c5e64bf. Report an issue: GitHub.