insufficient socket permissions (can_read=%v can_write=%v)

Error message

insufficient socket permissions (can_read=%v can_write=%v)

What it means

New() checks the discovered Docker socket's permissions (CanRead/CanWrite on socketInfo) before creating the client. If the current process cannot both read and write the unix socket, it returns this error naming the actual permission bits. A Docker API client needs read+write on the socket to send requests and receive responses.

Source

Thrown at pkg/docker/dockerclient/client.go:229

		client, err = docker.NewClientFromEnv()
		if err != nil {
			return nil, err
		}

		log.Debug("dockerclient.New: new Docker client (env) [5]")

	case config.Host == "" && config.Env[EnvDockerHost] == "":
		socketInfo, err := GetUnixSocketAddr()
		if err != nil {
			return nil, err
		}

		if socketInfo == nil || socketInfo.Address == "" {
			return nil, fmt.Errorf("no unix socket found")
		}

		if socketInfo.CanRead == false || socketInfo.CanWrite == false {
			return nil, fmt.Errorf("insufficient socket permissions (can_read=%v can_write=%v)", socketInfo.CanRead, socketInfo.CanWrite)
		}

		config.Host = socketInfo.Address
		client, err = docker.NewVersionedClient(config.Host, config.APIVersion)
		if err != nil {
			return nil, err
		}

		if config.APIVersion != "" {
			client.SkipServerVersionCheck = true
		}

		log.Debug("dockerclient.New: new Docker client (default) [6]")

	default:
		return nil, ErrNoDockerInfo
	}

View on GitHub (pinned to 81940d17fa)

Solutions

Run the process as root or add your user to the docker group: sudo usermod -aG docker $USER, then re-login.
Mount the socket without :ro in containers: -v /var/run/docker.sock:/var/run/docker.sock (not :ro).
Check the socket mode: ls -l /var/run/docker.sock, and chmod/adjust group membership as appropriate.
Check for SELinux/AppArmor denials (audit logs) and adjust policy or use --privileged where acceptable.

Example fix

// before
docker run --rm -u 1000 -v /var/run/docker.sock:/var/run/docker.sock:ro my-tool
// after
docker run --rm -u 1000 --group-add $(stat -g %g /var/run/docker.sock) -v /var/run/docker.sock:/var/run/docker.sock my-tool

Defensive patterns

Strategy: validation

Validate before calling

func canUseDockerSocket(path string) error {
    if err := unix.Access(path, unix.R_OK); err != nil {
        return fmt.Errorf("cannot read %s: %w", path, err)
    }
    if err := unix.Access(path, unix.W_OK); err != nil {
        return fmt.Errorf("cannot write %s: %w", path, err)
    }
    return nil
}

Try / catch

cli, err := dockerclient.New(cfg)
if err != nil {
    if strings.Contains(err.Error(), "insufficient socket permissions") {
        return fmt.Errorf("add user to docker group or run as root, and mount socket rw: %w", err)
    }
    return err
}

Prevention

Add the running user to the docker group (usermod -aG docker) or run as root.
Mount the socket without :ro in containers.
Avoid restrictive SELinux/AppArmor profiles blocking socket access; audit denials.
Preflight the socket with a read/write access check before building the client.

When it happens

Trigger: Calling New (directly or via OnCommand, OnPullCommand, OnPushCommand, etc.) when the socket file exists but the process lacks read or write permission on it — e.g. socket owned by root:docker with mode 0660 and the user is not in the docker group.

Common situations: Running a tool inside a container as non-root with a mounted docker.sock; user not added to the docker group; SELinux/AppArmor restricting socket access; mounting the socket read-only (:ro) into a container.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/84fab132228517e8. Report an issue: GitHub.