golang/go · error

invalid mode: %s

Error message

invalid mode: %s

What it means

Thrown by the chmod command in the Go test script framework when the mode argument fails strconv.ParseUint or when the parsed permission value has bits outside the fs.ModePerm mask (0o777). Only numeric permissions are supported (no symbolic modes like 'u+x'). The validation combines parse success and a bitmask check.

Source

Thrown at src/cmd/internal/script/cmds.go:177

// Chmod changes the permissions of a file or a directory..
func Chmod() Cmd {
	return Command(
		CmdUsage{
			Summary: "change file mode bits",
			Args:    "perm paths...",
			Detail: []string{
				"Changes the permissions of the named files or directories to be equal to perm.",
				"Only numerical permissions are supported.",
			},
		},
		func(s *State, args ...string) (WaitFunc, error) {
			if len(args) < 2 {
				return nil, ErrUsage
			}

			perm, err := strconv.ParseUint(args[0], 0, 32)
			if err != nil || perm&uint64(fs.ModePerm) != perm {
				return nil, fmt.Errorf("invalid mode: %s", args[0])
			}

			for _, arg := range args[1:] {
				err := os.Chmod(s.Path(arg), fs.FileMode(perm))
				if err != nil {
					return nil, err
				}
			}
			return nil, nil
		})
}

// Cmp compares the contents of two files, or the contents of either the
// "stdout" or "stderr" buffer and a file, returning a non-nil error if the
// contents differ.
func Cmp() Cmd {
	return Command(
		CmdUsage{

View on GitHub (pinned to b6b368adc5)

Solutions

1. Use numeric octal notation for the mode, e.g. `chmod 0755 file` or `chmod 0644 file`.
2. Ensure the permission value does not exceed 0o777 (511 decimal).
3. Use the 0o prefix for clarity: `chmod 0o755 file`.

Example fix

// Before (broken): chmod u+x script.sh
// After (fixed):  chmod 0755 script.sh

// Validate mode is numeric and within ModePerm before chmod:
func validateChmodMode(modeStr string) error {
    perm, err := strconv.ParseUint(modeStr, 0, 32)
    if err != nil {
        return fmt.Errorf("mode must be numeric: %w", err)
    }
    if perm & uint64(fs.ModePerm) != perm {
        return fmt.Errorf("mode %o has bits beyond 0o777", perm)
    }
    return nil
}

When it happens

Trigger: args[0] to chmod is not a valid unsigned integer parseable by strconv.ParseUint with base 0 (supports 0o, 0x prefixes), OR perm & 0o777 != perm meaning extra bits beyond the 9 permission bits are set.

Common situations: Using symbolic chmod notation ('u+x', 'g-w', 'a=r') in a Go test script, which is not supported. Also using octal with wrong prefix or values exceeding 0o777.

Related errors

• %s and %s differ
• %w: output pipes not closed after waiting %v
• %s exists but is writable
• %s exists but is not executable
• bad -count=: %v

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/0dd3c2ecd09c9a9e. Report an issue: GitHub.